# sanjithsece/tamil-transcript- architecture

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

- Interactive diagram: https://gitdiagram.com/sanjithsece/tamil-transcript-
- Repository: https://github.com/sanjithsece/tamil-transcript-

## Overview

#### Purpose and Entry Points
OLA-AI is a manuscript-digitization MVP: it ingests Tamil palm-leaf images/documents, produces preserved/restored assets and text-derived metadata, exposes a searchable archive and grounded Q&A, and presents workflows in a React SPA. Backend startup is `backend/app/main.py`; frontend startup is `frontend/src/main.tsx`. Local multi-service execution is defined by `docker-compose.yml`.

#### Client Application
The Vite/React TypeScript frontend provides public, authenticated, researcher, and admin experiences. Routing/pages cover upload-digitization, archive browsing, manuscript detail, dashboard analytics, login/registration, and administration in `frontend/src/pages/DigitizePage.tsx`, `frontend/src/pages/ArchivePage.tsx`, and `frontend/src/pages/ManuscriptPage.tsx`. `frontend/src/services/api.ts` is the HTTP boundary to FastAPI; `frontend/src/contexts/AuthContext.tsx` owns client authentication state. The manuscript Q&A interaction is encapsulated in `frontend/src/components/AskManuscript.tsx`.

#### API, Auth, and Authorization
FastAPI composes health/API behavior and cross-origin access in `backend/app/main.py`. Route modules separate authentication, manuscript lifecycle, archive/search, and administrative controls: `backend/app/api/auth.py`, `backend/app/api/manuscripts.py`, `backend/app/api/archive.py`, and `backend/app/api/admin.py`. JWT issuance/validation and bcrypt password handling are centralized in `backend/app/auth/security.py`, placing authorization at the API boundary before protected upload and management actions.

#### Persistence and Asset Storage
SQLAlchemy configuration and domain entities establish the durable model boundary in `backend/app/config/database.py` and `backend/app/models/entities.py`. Manuscript-oriented reads/writes are isolated behind `backend/app/repositories/manuscript_repository.py`, while orchestration belongs in `backend/app/services/manuscript_service.py`. `backend/app/services/storage_service.py` abstracts original and restored file persistence: local storage supports demo development, while Supabase Storage is the deploy target. Database deployment can move from SQLite to Supabase PostgreSQL without changing API consumers.

#### Digitization Pipeline
Manuscript submission flows from the API/service layer through asset storage and a staged processing pipeline: image restoration/preprocessing, OCR, Tamil cleanup, AI interpretation/translation fallback, then searchable/indexable manuscript data. The concrete stage boundaries are `backend/app/preprocessing/image_processor.py`, `backend/app/ocr/ocr_service.py`, `backend/app/services/tamil_text_processor.py`, and `backend/app/ai/providers.py`. These replaceable service abstractions allow OpenCV/Pillow preprocessing, an optional Tamil-capable OCR engine, and provider-backed or fallback AI behavior without coupling routes to implementations.

#### Retrieval and Archive Flow
Archive endpoints search Tamil Unicode content across manuscript fields, returning persisted records through repository/service layers. For “Ask the Manuscript,” `backend/app/rag/rag_service.py` retrieves manuscript text chunks and constrains answers to that retrieved context; the API exposes this capability through `backend/app/api/manuscripts.py` and the frontend consumes it via `frontend/src/components/AskManuscript.tsx`. This creates a distinct retrieval boundary from generative/interpretive AI processing.

#### Runtime and External Services
The backend is Python/FastAPI with SQLAlchemy and configured environment settings in `backend/app/config/settings.py`; the frontend is React/Vite. `backend/Dockerfile`, `frontend/Dockerfile`, and `docker-compose.yml` support containerized local operation. Material external integrations are Supabase PostgreSQL and object storage, optional OCR/Tesseract Tamil data, and configurable AI providers. Demo mode seeds representative records through `backend/app/services/demo_data.py` and sample assets under `sample-data/`.

Main entry points: [`backend/app/api/manuscripts.py`](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/api/manuscripts.py) (Route Modules), [`backend/app/services/manuscript_service.py`](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/manuscript_service.py) (Manuscript Service), [`frontend/src/services/api.ts`](https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/services/api.ts) (API Client), [`backend/app/repositories/manuscript_repository.py`](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/repositories/manuscript_repository.py) (Manuscript Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Client"]
  node_frontend_app["React SPA<br/>Vite/React entry<br/>[main.tsx]"]
  node_frontend_pages["Workflow Pages<br/>React pages<br/>[DigitizePage.tsx]"]
  node_client_api["API Client<br/>HTTP boundary<br/>[api.ts]"]
  node_auth_context["Auth State<br/>React context<br/>[AuthContext.tsx]"]
  node_ask_ui["Ask Manuscript<br/>Q&amp;A component<br/>[AskManuscript.tsx]"]
end

subgraph group_api["FastAPI Backend"]
  node_fastapi_app["FastAPI App<br/>API composition<br/>[main.py]"]
  node_routes["Route Modules<br/>API routes<br/>[manuscripts.py]"]
  node_security["JWT Security<br/>authentication<br/>[security.py]"]
  node_manuscript_service["Manuscript Service<br/>application service"]
end

subgraph group_pipeline["Digitization &amp; Retrieval"]
  node_image_processor["Image Restoration<br/>preprocessing stage<br/>[image_processor.py]"]
  node_ocr["Tamil OCR<br/>OCR stage<br/>[ocr_service.py]"]
  node_tamil_cleanup["Tamil Text Cleanup<br/>text processing stage"]
  node_ai_providers["AI Interpretation<br/>provider abstraction<br/>[providers.py]"]
  node_rag["Grounded RAG<br/>retrieval service<br/>[rag_service.py]"]
end

subgraph group_data["Persistence &amp; Integrations"]
  node_repository["Manuscript Repository<br/>data access"]
  node_domain_model["Domain Entities<br/>SQLAlchemy models<br/>[entities.py]"]
  node_database[("SQL Database<br/>SQLite / Supabase PostgreSQL<br/>[database.py]")]
  node_storage_service["Asset Storage Service<br/>storage abstraction<br/>[storage_service.py]"]
  node_object_storage[("Object Storage<br/>local / Supabase Storage")]
  node_compose{{"Local Containers<br/>Docker Compose<br/>[docker-compose.yml]"}}
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_pages -->|"calls"| node_client_api
node_auth_context -->|"supplies JWT"| node_client_api
node_ask_ui -->|"submits questions"| node_client_api
node_client_api -->|"HTTP"| node_fastapi_app
node_fastapi_app -->|"mounts"| node_routes
node_routes -->|"authenticates"| node_security
node_routes -->|"lifecycle and archive requests"| node_manuscript_service
node_routes -->|"Ask Manuscript"| node_rag
node_manuscript_service -->|"stores assets"| node_storage_service
node_storage_service -->|"persists files"| node_object_storage
node_manuscript_service -->|"processes uploads"| node_image_processor
node_image_processor -->|"prepared image"| node_ocr
node_ocr -->|"raw text"| node_tamil_cleanup
node_tamil_cleanup -->|"cleaned Tamil text"| node_ai_providers
node_manuscript_service -->|"reads and writes"| node_repository
node_ai_providers -->|"derived metadata"| node_repository
node_repository -->|"maps"| node_domain_model
node_domain_model -->|"persists"| node_database
node_rag -->|"retrieves text chunks"| node_repository
node_compose -->|"runs"| node_frontend_app
node_compose -->|"runs"| node_fastapi_app

click node_frontend_app "https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/main.tsx"
click node_frontend_pages "https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/pages/DigitizePage.tsx"
click node_client_api "https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/services/api.ts"
click node_auth_context "https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_ask_ui "https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/components/AskManuscript.tsx"
click node_fastapi_app "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/main.py"
click node_routes "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/api/manuscripts.py"
click node_security "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/auth/security.py"
click node_manuscript_service "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/manuscript_service.py"
click node_repository "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/repositories/manuscript_repository.py"
click node_domain_model "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/models/entities.py"
click node_database "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/config/database.py"
click node_storage_service "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/storage_service.py"
click node_image_processor "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/preprocessing/image_processor.py"
click node_ocr "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/ocr/ocr_service.py"
click node_tamil_cleanup "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/tamil_text_processor.py"
click node_ai_providers "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/ai/providers.py"
click node_rag "https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/rag/rag_service.py"
click node_compose "https://github.com/sanjithsece/tamil-transcript-/blob/main/docker-compose.yml"

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_frontend_app,node_frontend_pages,node_client_api,node_auth_context,node_ask_ui toneBlue
class node_fastapi_app,node_routes,node_security,node_manuscript_service toneAmber
class node_image_processor,node_ocr,node_tamil_cleanup,node_ai_providers,node_rag toneMint
class node_repository,node_domain_model,node_database,node_storage_service,node_object_storage,node_compose toneRose
```

## Components

### React Client

- [React SPA](https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/main.tsx): Vite/React entry · Public, researcher, and admin workflows. · `frontend/src/main.tsx`
- [Workflow Pages](https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/pages/DigitizePage.tsx): React pages · Digitization, archive, and manuscript detail views. · `frontend/src/pages/DigitizePage.tsx`
- [API Client](https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/services/api.ts): HTTP boundary · `frontend/src/services/api.ts`
- [Auth State](https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/contexts/AuthContext.tsx): React context · `frontend/src/contexts/AuthContext.tsx`
- [Ask Manuscript](https://github.com/sanjithsece/tamil-transcript-/blob/main/frontend/src/components/AskManuscript.tsx): Q&A component · `frontend/src/components/AskManuscript.tsx`

### FastAPI Backend

- [FastAPI App](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/main.py): API composition · Hosts health, API routes, and CORS. · `backend/app/main.py`
- [Route Modules](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/api/manuscripts.py): API routes · Authentication, manuscript, archive, and admin endpoints. · `backend/app/api/manuscripts.py`
- [JWT Security](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/auth/security.py): authentication · Issues and validates JWTs and hashes passwords. · `backend/app/auth/security.py`
- [Manuscript Service](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/manuscript_service.py): application service · Orchestrates lifecycle, processing, and persistence. · `backend/app/services/manuscript_service.py`

### Digitization & Retrieval

- [Image Restoration](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/preprocessing/image_processor.py): preprocessing stage · Prepares palm-leaf imagery for OCR. · `backend/app/preprocessing/image_processor.py`
- [Tamil OCR](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/ocr/ocr_service.py): OCR stage · Uses an optional Tamil-capable OCR engine. · `backend/app/ocr/ocr_service.py`
- [Tamil Text Cleanup](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/tamil_text_processor.py): text processing stage · `backend/app/services/tamil_text_processor.py`
- [AI Interpretation](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/ai/providers.py): provider abstraction · Provider-backed translation/interpretation with fallback behavior. · `backend/app/ai/providers.py`
- [Grounded RAG](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/rag/rag_service.py): retrieval service · Answers only from retrieved manuscript text chunks. · `backend/app/rag/rag_service.py`

### Persistence & Integrations

- [Manuscript Repository](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/repositories/manuscript_repository.py): data access · `backend/app/repositories/manuscript_repository.py`
- [Domain Entities](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/models/entities.py): SQLAlchemy models · `backend/app/models/entities.py`
- [SQL Database](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/config/database.py): SQLite / Supabase PostgreSQL · Durable manuscript records and searchable fields. · `backend/app/config/database.py`
- [Asset Storage Service](https://github.com/sanjithsece/tamil-transcript-/blob/main/backend/app/services/storage_service.py): storage abstraction · Persists original and restored files. · `backend/app/services/storage_service.py`
- **Object Storage**: local / Supabase Storage
- [Local Containers](https://github.com/sanjithsece/tamil-transcript-/blob/main/docker-compose.yml): Docker Compose · Runs frontend and backend services locally. · `docker-compose.yml`

## Connections

- React SPA → Workflow Pages: renders
- Workflow Pages → API Client: calls
- Auth State → API Client: supplies JWT
- Ask Manuscript → API Client: submits questions
- API Client → FastAPI App: HTTP
- FastAPI App → Route Modules: mounts
- Route Modules → JWT Security: authenticates
- Route Modules → Manuscript Service: lifecycle and archive requests
- Route Modules → Grounded RAG: Ask Manuscript
- Manuscript Service → Asset Storage Service: stores assets
- Asset Storage Service → Object Storage: persists files
- Manuscript Service → Image Restoration: processes uploads
- Image Restoration → Tamil OCR: prepared image
- Tamil OCR → Tamil Text Cleanup: raw text
- Tamil Text Cleanup → AI Interpretation: cleaned Tamil text
- Manuscript Service → Manuscript Repository: reads and writes
- AI Interpretation → Manuscript Repository: derived metadata
- Manuscript Repository → Domain Entities: maps
- Domain Entities → SQL Database: persists
- Grounded RAG → Manuscript Repository: retrieves text chunks
- Local Containers → React SPA: runs
- Local Containers → FastAPI App: runs