# tharik1305/kallvettu architecture

> Architecture diagram of the GitHub repository tharik1305/kallvettu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tharik1305/kallvettu
- Repository: https://github.com/tharik1305/kallvettu

## Overview

Kallvettu is a scholarly epigraphy platform: researchers submit an inscription image or curated/manual reading, enhance the image, compare OCR evidence, review the transcription, and obtain translations and historical interpretation. The workbench also supports lexical analysis, research storage and review, search, visual exploration, geographic context, and scholarly exports. The README documents the broad workflow and capabilities; sampled source supports key module responsibilities, but not every runtime connection, so uncertain subsystem links are omitted.

Main entry points: [`app.py`](https://github.com/tharik1305/kallvettu/blob/main/app.py) (Inscription workbench), [`services/api/app.py`](https://github.com/tharik1305/kallvettu/blob/main/services/api/app.py) (Research API), [`services/ai/common/provider_manager.py`](https://github.com/tharik1305/kallvettu/blob/main/services/ai/common/provider_manager.py) (OCR provider manager), [`services/database/repository.py`](https://github.com/tharik1305/kallvettu/blob/main/services/database/repository.py) (Research repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Workbench and workflow"]
  node_app["Inscription workbench<br/>[app.py]"]
end

subgraph group_reading["Image reading and language"]
  node_restoration["Image restoration"]
  node_provider_manager["OCR provider manager"]
  node_ocr_providers["OCR providers"]
  node_comparison["OCR comparison"]
  node_fusion["Evidence fusion<br/>[fusion_engine.py]"]
  node_review["Scholar adjudication"]
  node_translation["Tamil NLP and translation"]
end

subgraph group_scholarship["Scholarly research"]
  node_lexicon["Classical dictionary"]
  node_database[("Research database<br/>[models.py]")]
  node_repository["Research repository<br/>[repository.py]"]
  node_collaboration["Collaborative review<br/>[review_service.py]"]
  node_glyph_dataset["Glyph dataset"]
  node_evaluation["Research evaluation"]
end

subgraph group_presentation["Exploration and export"]
  node_search["Epigraphical search<br/>[search_engine.py]"]
  node_knowledge_graph["Historical knowledge graph<br/>[graph_engine.py]"]
  node_atlas["Geographic atlas"]
  node_iiif["IIIF deep zoom"]
  node_epidoc["EpiDoc and research bundles<br/>[bundle.py]"]
  node_api["Research API<br/>[app.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits inscription"| node_app
node_app -->|"restores image"| node_restoration
node_app -->|"requests OCR"| node_provider_manager
node_provider_manager -->|"dispatches to"| node_ocr_providers
node_app -->|"compares readings"| node_comparison
node_app -->|"fuses evidence"| node_fusion
node_app -->|"supports adjudication"| node_review
node_app -->|"translates and interprets"| node_translation
node_app -->|"offers lexical analysis"| node_lexicon
node_app -.->|"records research"| node_repository
node_repository -->|"persists records"| node_database
node_app -.->|"supports review"| node_collaboration
node_app -->|"supports annotation"| node_glyph_dataset
node_app -->|"runs benchmarks"| node_evaluation
node_app -->|"searches corpus"| node_search
node_app -->|"visualizes context"| node_knowledge_graph
node_app -->|"maps sites"| node_atlas
node_app -->|"opens deep zoom"| node_iiif
node_app -->|"exports archives"| node_epidoc
node_researcher -->|"queries catalog"| node_api
node_api -->|"provides search"| node_search
node_api -->|"serves bundles"| node_epidoc
node_api -->|"serves manifests"| node_iiif

click node_app "https://github.com/tharik1305/kallvettu/blob/main/app.py"
click node_restoration "https://github.com/tharik1305/kallvettu/blob/main/restoration_engine.py"
click node_provider_manager "https://github.com/tharik1305/kallvettu/blob/main/services/ai/common/provider_manager.py"
click node_ocr_providers "https://github.com/tharik1305/kallvettu/tree/main/services/ai"
click node_comparison "https://github.com/tharik1305/kallvettu/blob/main/services/ai/common/comparison_engine.py"
click node_fusion "https://github.com/tharik1305/kallvettu/blob/main/services/ocr_fusion/fusion_engine.py"
click node_review "https://github.com/tharik1305/kallvettu/blob/main/services/ocr_fusion/researcher_review.py"
click node_translation "https://github.com/tharik1305/kallvettu/blob/main/nlp_translation_engine.py"
click node_lexicon "https://github.com/tharik1305/kallvettu/blob/main/services/nlp/classical_dictionary.py"
click node_database "https://github.com/tharik1305/kallvettu/blob/main/services/database/models.py"
click node_repository "https://github.com/tharik1305/kallvettu/blob/main/services/database/repository.py"
click node_collaboration "https://github.com/tharik1305/kallvettu/blob/main/services/collaboration/review_service.py"
click node_glyph_dataset "https://github.com/tharik1305/kallvettu/blob/main/services/research/historical_glyph_dataset.py"
click node_evaluation "https://github.com/tharik1305/kallvettu/blob/main/services/evaluation/research_benchmark.py"
click node_search "https://github.com/tharik1305/kallvettu/blob/main/services/search/search_engine.py"
click node_knowledge_graph "https://github.com/tharik1305/kallvettu/blob/main/services/knowledge_graph/graph_engine.py"
click node_atlas "https://github.com/tharik1305/kallvettu/tree/main/services/geo_atlas"
click node_iiif "https://github.com/tharik1305/kallvettu/blob/main/services/iiif/viewer_component.py"
click node_epidoc "https://github.com/tharik1305/kallvettu/blob/main/services/epidoc/bundle.py"
click node_api "https://github.com/tharik1305/kallvettu/blob/main/services/api/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_restoration,node_provider_manager,node_ocr_providers,node_comparison,node_fusion,node_review,node_translation toneAmber
class node_lexicon,node_database,node_repository,node_collaboration,node_glyph_dataset,node_evaluation toneMint
class node_search,node_knowledge_graph,node_atlas,node_iiif,node_epidoc,node_api toneRose
class node_researcher toneIndigo
```

## Components

### Workbench and workflow

- [Inscription workbench](https://github.com/tharik1305/kallvettu/blob/main/app.py): `app.py`

### Image reading and language

- [Image restoration](https://github.com/tharik1305/kallvettu/blob/main/restoration_engine.py): `restoration_engine.py`
- [OCR provider manager](https://github.com/tharik1305/kallvettu/blob/main/services/ai/common/provider_manager.py): `services/ai/common/provider_manager.py`
- [OCR providers](https://github.com/tharik1305/kallvettu/tree/main/services/ai): `services/ai`
- [OCR comparison](https://github.com/tharik1305/kallvettu/blob/main/services/ai/common/comparison_engine.py): `services/ai/common/comparison_engine.py`
- [Evidence fusion](https://github.com/tharik1305/kallvettu/blob/main/services/ocr_fusion/fusion_engine.py): `services/ocr_fusion/fusion_engine.py`
- [Scholar adjudication](https://github.com/tharik1305/kallvettu/blob/main/services/ocr_fusion/researcher_review.py): `services/ocr_fusion/researcher_review.py`
- [Tamil NLP and translation](https://github.com/tharik1305/kallvettu/blob/main/nlp_translation_engine.py): `nlp_translation_engine.py`

### Scholarly research

- [Classical dictionary](https://github.com/tharik1305/kallvettu/blob/main/services/nlp/classical_dictionary.py): `services/nlp/classical_dictionary.py`
- [Research database](https://github.com/tharik1305/kallvettu/blob/main/services/database/models.py): `services/database/models.py`
- [Research repository](https://github.com/tharik1305/kallvettu/blob/main/services/database/repository.py): `services/database/repository.py`
- [Collaborative review](https://github.com/tharik1305/kallvettu/blob/main/services/collaboration/review_service.py): `services/collaboration/review_service.py`
- [Glyph dataset](https://github.com/tharik1305/kallvettu/blob/main/services/research/historical_glyph_dataset.py): `services/research/historical_glyph_dataset.py`
- [Research evaluation](https://github.com/tharik1305/kallvettu/blob/main/services/evaluation/research_benchmark.py): `services/evaluation/research_benchmark.py`

### Exploration and export

- [Epigraphical search](https://github.com/tharik1305/kallvettu/blob/main/services/search/search_engine.py): `services/search/search_engine.py`
- [Historical knowledge graph](https://github.com/tharik1305/kallvettu/blob/main/services/knowledge_graph/graph_engine.py): `services/knowledge_graph/graph_engine.py`
- [Geographic atlas](https://github.com/tharik1305/kallvettu/tree/main/services/geo_atlas): `services/geo_atlas`
- [IIIF deep zoom](https://github.com/tharik1305/kallvettu/blob/main/services/iiif/viewer_component.py): `services/iiif/viewer_component.py`
- [EpiDoc and research bundles](https://github.com/tharik1305/kallvettu/blob/main/services/epidoc/bundle.py): `services/epidoc/bundle.py`
- [Research API](https://github.com/tharik1305/kallvettu/blob/main/services/api/app.py): `services/api/app.py`

### Other components

- **Researcher**

## Connections

- Researcher → Inscription workbench: submits inscription
- Inscription workbench → Image restoration: restores image (evidence: `app.py`)
- Inscription workbench → OCR provider manager: requests OCR (evidence: `app.py`)
- OCR provider manager → OCR providers: dispatches to (evidence: `services/ai/common/provider_manager.py`)
- Inscription workbench → OCR comparison: compares readings (evidence: `app.py`)
- Inscription workbench → Evidence fusion: fuses evidence
- Inscription workbench → Scholar adjudication: supports adjudication (evidence: `app.py`)
- Inscription workbench → Tamil NLP and translation: translates and interprets (evidence: `app.py`)
- Inscription workbench → Classical dictionary: offers lexical analysis
- Inscription workbench → Research repository: records research
- Research repository → Research database: persists records (evidence: `services/database/repository.py`)
- Inscription workbench → Collaborative review: supports review
- Inscription workbench → Glyph dataset: supports annotation
- Inscription workbench → Research evaluation: runs benchmarks
- Inscription workbench → Epigraphical search: searches corpus
- Inscription workbench → Historical knowledge graph: visualizes context
- Inscription workbench → Geographic atlas: maps sites (evidence: `app.py`)
- Inscription workbench → IIIF deep zoom: opens deep zoom (evidence: `app.py`)
- Inscription workbench → EpiDoc and research bundles: exports archives (evidence: `app.py`)
- Researcher → Research API: queries catalog (evidence: `services/api/app.py`)
- Research API → Epigraphical search: provides search (evidence: `services/api/app.py`)
- Research API → EpiDoc and research bundles: serves bundles (evidence: `services/api/app.py`)
- Research API → IIIF deep zoom: serves manifests (evidence: `services/api/app.py`)
