# ckhot18/lipilensv2 architecture

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

- Interactive diagram: https://gitdiagram.com/ckhot18/lipilensv2
- Repository: https://github.com/ckhot18/lipilensv2

## Overview

LipiLens is a web application for drafting and human-verifying transcriptions of historical Modi manuscripts. Its main flow uploads a scan, restores it, segments it for model inference, archives the draft, and supports later review and search; restoration preview is a separate CPU-only path. The README also describes evaluation as a standalone capability. Some route-to-service relationships are supported by the SOURCE INDEX; unsampled internals and integrations are not expanded beyond documented behavior.

Main entry points: [`frontend/src/api/client.js`](https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/api/client.js) (HTTP client), [`backend/main.py`](https://github.com/ckhot18/lipilensv2/blob/main/backend/main.py) (FastAPI application), [`backend/services/pipeline.py`](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/pipeline.py) (Pipeline orchestration), [`backend/services/transcription/inference.py`](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/inference.py) (Inference selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_ui["LipiLens interface<br/>[App.jsx]"]
  node_transcribe_page["Transcribe page<br/>[Transcribe.jsx]"]
  node_library_page["Library page<br/>[Library.jsx]"]
  node_api_client["HTTP client<br/>[client.js]"]
end

subgraph group_api["API and workflow"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_manuscript_routes["Manuscript routes<br/>[manuscripts.py]"]
  node_preview_route["Preview route<br/>[preview.py]"]
  node_transcription_routes["Verification routes<br/>[transcriptions.py]"]
  node_health_route["Health route<br/>[health.py]"]
  node_workflow["Pipeline orchestration<br/>[pipeline.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_image["Image processing"]
  node_restoration["Restoration pipeline<br/>[pipeline.py]"]
  node_restoration_stages["Restoration stages<br/>[stages.py]"]
  node_image_io["Image I/O<br/>[image_io.py]"]
end

subgraph group_transcription["Transcription"]
  node_transcription_service["Inference selection<br/>[inference.py]"]
  node_segmentation["Line segmentation<br/>[segment.py]"]
  node_local_model["Local Qwen<br/>[local_qwen.py]"]
  node_colab_client["Colab client<br/>[colab_client.py]"]
  node_colab_server["Colab inference server"]
end

subgraph group_archive["Archive and evaluation"]
  node_archive_repo["Archive repository<br/>[repository.py]"]
  node_database[("SQLite archive<br/>[models.py]")]
  node_db_session["Database sessions<br/>[session.py]"]
  node_metrics["CER/WER evaluation<br/>[compute_metrics.py]"]
end

node_user(("Manuscript user"))

node_user -.->|"uses"| node_ui
node_ui -->|"opens"| node_transcribe_page
node_ui -->|"opens"| node_library_page
node_transcribe_page -->|"requests"| node_api_client
node_library_page -->|"requests"| node_api_client
node_api_client -->|"HTTP calls"| node_manuscript_routes
node_api_client -->|"previews"| node_preview_route
node_api_client -->|"verifies"| node_transcription_routes
node_api_client -->|"checks health"| node_health_route
node_api_app -->|"registers"| node_manuscript_routes
node_api_app -->|"registers"| node_preview_route
node_api_app -->|"registers"| node_transcription_routes
node_api_app -->|"registers"| node_health_route
node_api_app -->|"initializes"| node_db_session
node_manuscript_routes -->|"runs workflow"| node_workflow
node_manuscript_routes -->|"archives records"| node_archive_repo
node_preview_route -->|"runs preview"| node_restoration
node_preview_route -->|"saves images"| node_image_io
node_workflow -->|"restores image"| node_restoration
node_workflow -->|"loads and saves"| node_image_io
node_workflow -->|"transcribes image"| node_transcription_service
node_restoration -->|"dispatches stages"| node_restoration_stages
node_transcription_service -->|"segments lines"| node_segmentation
node_transcription_service -->|"selects locally"| node_local_model
node_transcription_service -->|"selects remotely"| node_colab_client
node_colab_client -.->|"sends inference request"| node_colab_server
node_transcription_routes -->|"verifies draft"| node_archive_repo
node_archive_repo -->|"reads and writes"| node_database
node_db_session -->|"creates tables"| node_database
node_manuscript_routes -->|"uses request session"| node_db_session
node_transcription_routes -->|"uses request session"| node_db_session
node_transcription_service -->|"selects mode"| node_config
node_workflow -->|"reads settings"| node_config
node_metrics -.->|"evaluates saved outputs"| node_archive_repo

click node_ui "https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/App.jsx"
click node_transcribe_page "https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/pages/Transcribe.jsx"
click node_library_page "https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/pages/Library.jsx"
click node_api_client "https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/api/client.js"
click node_api_app "https://github.com/ckhot18/lipilensv2/blob/main/backend/main.py"
click node_manuscript_routes "https://github.com/ckhot18/lipilensv2/blob/main/backend/api/manuscripts.py"
click node_preview_route "https://github.com/ckhot18/lipilensv2/blob/main/backend/api/preview.py"
click node_transcription_routes "https://github.com/ckhot18/lipilensv2/blob/main/backend/api/transcriptions.py"
click node_health_route "https://github.com/ckhot18/lipilensv2/blob/main/backend/api/health.py"
click node_workflow "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/pipeline.py"
click node_restoration "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/restoration/pipeline.py"
click node_restoration_stages "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/restoration/stages.py"
click node_image_io "https://github.com/ckhot18/lipilensv2/blob/main/backend/utils/image_io.py"
click node_transcription_service "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/inference.py"
click node_segmentation "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/segment.py"
click node_local_model "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/local_qwen.py"
click node_colab_client "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/colab_client.py"
click node_colab_server "https://github.com/ckhot18/lipilensv2/blob/main/colab/lipilens_colab_server.py"
click node_archive_repo "https://github.com/ckhot18/lipilensv2/blob/main/backend/services/archive/repository.py"
click node_database "https://github.com/ckhot18/lipilensv2/blob/main/backend/database/models.py"
click node_db_session "https://github.com/ckhot18/lipilensv2/blob/main/backend/database/session.py"
click node_metrics "https://github.com/ckhot18/lipilensv2/blob/main/experiments/evaluation/compute_metrics.py"
click node_config "https://github.com/ckhot18/lipilensv2/blob/main/backend/config.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_ui,node_transcribe_page,node_library_page,node_api_client,node_user toneBlue
class node_api_app,node_manuscript_routes,node_preview_route,node_transcription_routes,node_health_route,node_workflow,node_config toneAmber
class node_restoration,node_restoration_stages,node_image_io toneMint
class node_transcription_service,node_segmentation,node_local_model,node_colab_client,node_colab_server toneRose
class node_archive_repo,node_database,node_db_session,node_metrics toneIndigo
```

## Components

### Web interface

- [LipiLens interface](https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Transcribe page](https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/pages/Transcribe.jsx): `frontend/src/pages/Transcribe.jsx`
- [Library page](https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/pages/Library.jsx): `frontend/src/pages/Library.jsx`
- [HTTP client](https://github.com/ckhot18/lipilensv2/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API and workflow

- [FastAPI application](https://github.com/ckhot18/lipilensv2/blob/main/backend/main.py): `backend/main.py`
- [Manuscript routes](https://github.com/ckhot18/lipilensv2/blob/main/backend/api/manuscripts.py): `backend/api/manuscripts.py`
- [Preview route](https://github.com/ckhot18/lipilensv2/blob/main/backend/api/preview.py): `backend/api/preview.py`
- [Verification routes](https://github.com/ckhot18/lipilensv2/blob/main/backend/api/transcriptions.py): `backend/api/transcriptions.py`
- [Health route](https://github.com/ckhot18/lipilensv2/blob/main/backend/api/health.py): `backend/api/health.py`
- [Pipeline orchestration](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/pipeline.py): `backend/services/pipeline.py`
- [Runtime configuration](https://github.com/ckhot18/lipilensv2/blob/main/backend/config.py): `backend/config.py`

### Image processing

- [Restoration pipeline](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/restoration/pipeline.py): `backend/services/restoration/pipeline.py`
- [Restoration stages](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/restoration/stages.py): `backend/services/restoration/stages.py`
- [Image I/O](https://github.com/ckhot18/lipilensv2/blob/main/backend/utils/image_io.py): `backend/utils/image_io.py`

### Transcription

- [Inference selection](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/inference.py): `backend/services/transcription/inference.py`
- [Line segmentation](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/segment.py): `backend/services/transcription/segment.py`
- [Local Qwen](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/local_qwen.py): `backend/services/transcription/local_qwen.py`
- [Colab client](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/transcription/colab_client.py): `backend/services/transcription/colab_client.py`
- [Colab inference server](https://github.com/ckhot18/lipilensv2/blob/main/colab/lipilens_colab_server.py): `colab/lipilens_colab_server.py`

### Archive and evaluation

- [Archive repository](https://github.com/ckhot18/lipilensv2/blob/main/backend/services/archive/repository.py): `backend/services/archive/repository.py`
- [SQLite archive](https://github.com/ckhot18/lipilensv2/blob/main/backend/database/models.py): `backend/database/models.py`
- [Database sessions](https://github.com/ckhot18/lipilensv2/blob/main/backend/database/session.py): `backend/database/session.py`
- [CER/WER evaluation](https://github.com/ckhot18/lipilensv2/blob/main/experiments/evaluation/compute_metrics.py): `experiments/evaluation/compute_metrics.py`

### Other components

- **Manuscript user**

## Connections

- Manuscript user → LipiLens interface: uses
- LipiLens interface → Transcribe page: opens (evidence: `frontend/src/App.jsx`)
- LipiLens interface → Library page: opens (evidence: `frontend/src/App.jsx`)
- Transcribe page → HTTP client: requests (evidence: `frontend/src/pages/Transcribe.jsx`)
- Library page → HTTP client: requests (evidence: `frontend/src/pages/Library.jsx`)
- HTTP client → Manuscript routes: HTTP calls (evidence: `frontend/src/api/client.js`)
- HTTP client → Preview route: previews (evidence: `frontend/src/api/client.js`)
- HTTP client → Verification routes: verifies (evidence: `frontend/src/api/client.js`)
- HTTP client → Health route: checks health (evidence: `frontend/src/api/client.js`)
- FastAPI application → Manuscript routes: registers (evidence: `backend/main.py`)
- FastAPI application → Preview route: registers (evidence: `backend/main.py`)
- FastAPI application → Verification routes: registers (evidence: `backend/main.py`)
- FastAPI application → Health route: registers (evidence: `backend/main.py`)
- FastAPI application → Database sessions: initializes (evidence: `backend/main.py`)
- Manuscript routes → Pipeline orchestration: runs workflow (evidence: `backend/api/manuscripts.py`)
- Manuscript routes → Archive repository: archives records (evidence: `backend/api/manuscripts.py`)
- Preview route → Restoration pipeline: runs preview (evidence: `backend/api/preview.py`)
- Preview route → Image I/O: saves images (evidence: `backend/api/preview.py`)
- Pipeline orchestration → Restoration pipeline: restores image (evidence: `backend/services/pipeline.py`)
- Pipeline orchestration → Image I/O: loads and saves (evidence: `backend/services/pipeline.py`)
- Pipeline orchestration → Inference selection: transcribes image (evidence: `backend/services/pipeline.py`)
- Restoration pipeline → Restoration stages: dispatches stages (evidence: `backend/services/restoration/pipeline.py`)
- Inference selection → Line segmentation: segments lines (evidence: `backend/services/transcription/inference.py`)
- Inference selection → Local Qwen: selects locally (evidence: `backend/services/transcription/inference.py`)
- Inference selection → Colab client: selects remotely (evidence: `backend/services/transcription/inference.py`)
- Colab client → Colab inference server: sends inference request
- Verification routes → Archive repository: verifies draft (evidence: `backend/api/transcriptions.py`)
- Archive repository → SQLite archive: reads and writes (evidence: `backend/services/archive/repository.py`)
- Database sessions → SQLite archive: creates tables (evidence: `backend/database/session.py`)
- Manuscript routes → Database sessions: uses request session (evidence: `backend/api/manuscripts.py`)
- Verification routes → Database sessions: uses request session (evidence: `backend/api/transcriptions.py`)
- Inference selection → Runtime configuration: selects mode (evidence: `backend/services/transcription/inference.py`)
- Pipeline orchestration → Runtime configuration: reads settings (evidence: `backend/services/pipeline.py`)
- CER/WER evaluation → Archive repository: evaluates saved outputs
