# protei300/russiandocsocr architecture

> Architecture diagram of the GitHub repository protei300/russiandocsocr, 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/protei300/russiandocsocr
- Repository: https://github.com/protei300/russiandocsocr

## Overview

RussianDocsOCR recognizes and validates Russian identity documents from a single image. The main workflow is upload through the REST service, queued background recognition, document-processing inference, and stored results presented in the web interface. The repository also documents Go, .NET, and Kotlin/JVM implementations intended to match the Python reference. Processing stages and service boundaries are grounded in the README and sampled source; some API-to-queue and UI wiring is documented rather than directly shown in the excerpts.

Main entry points: [`document_processing/pipeline/pipeline.py`](https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline/pipeline.py) (Recognition pipeline), [`service/worker.py`](https://github.com/protei300/russiandocsocr/blob/main/service/worker.py) (Recognition worker), [`service/ml/runtime.py`](https://github.com/protei300/russiandocsocr/blob/main/service/ml/runtime.py) (ML runtime), [`service/api/documents.py`](https://github.com/protei300/russiandocsocr/blob/main/service/api/documents.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web interface<br/>[App.vue]"]
end

subgraph group_service["REST service"]
  node_api["REST API<br/>[documents.py]"]
  node_worker["Recognition worker<br/>[worker.py]"]
  node_runtime["ML runtime<br/>[runtime.py]"]
  node_transform["Result transform<br/>[transform.py]"]
end

subgraph group_processing["Document processing"]
  node_pipeline["Recognition pipeline<br/>[pipeline.py]"]
  node_quality["Quality and fraud checks"]
  node_document["Document detection<br/>[doc_detector.py]"]
  node_registration["Page registration"]
  node_fields["Field localization"]
  node_ocr["OCR and correction<br/>[ocr_batch.py]"]
  node_validation["MRZ validation<br/>[mrz.py]"]
  node_ports["Cross-language ports"]
end

subgraph group_state["Service state"]
  node_repositories["Document repositories<br/>[documents.py]"]
  node_store[("File-backed store<br/>[database.py]")]
  node_settings["Storage selection<br/>[storage_mode.py]"]
end

node_operator(("Operator"))
node_browser(("Browser user"))

node_browser -->|"uses"| node_web
node_operator -->|"uploads image"| node_api
node_web -->|"calls REST"| node_api
node_api -->|"queues recognition"| node_worker
node_worker -->|"runs recognition"| node_runtime
node_runtime -.->|"invokes pipeline"| node_pipeline
node_pipeline -->|"checks quality"| node_quality
node_pipeline -->|"detects document"| node_document
node_pipeline -->|"registers page"| node_registration
node_pipeline -->|"localizes fields"| node_fields
node_pipeline -->|"recognizes text"| node_ocr
node_pipeline -.->|"validates MRZ"| node_validation
node_runtime -.->|"formats results"| node_transform
node_worker -->|"reads and writes"| node_repositories
node_repositories -.->|"persists records"| node_store
node_settings -->|"selects backend"| node_store
node_operator -.->|"can use alternatives"| node_ports

click node_web "https://github.com/protei300/russiandocsocr/blob/main/web/src/App.vue"
click node_api "https://github.com/protei300/russiandocsocr/blob/main/service/api/documents.py"
click node_worker "https://github.com/protei300/russiandocsocr/blob/main/service/worker.py"
click node_runtime "https://github.com/protei300/russiandocsocr/blob/main/service/ml/runtime.py"
click node_transform "https://github.com/protei300/russiandocsocr/blob/main/service/ml/transform.py"
click node_pipeline "https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline/pipeline.py"
click node_quality "https://github.com/protei300/russiandocsocr/tree/main/document_processing/pipeline_modules"
click node_document "https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/doc_detector/doc_detector.py"
click node_registration "https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/page_registration/page_registration.py"
click node_fields "https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/textfields_detector/textfields_detector.py"
click node_ocr "https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/ocr_batch.py"
click node_validation "https://github.com/protei300/russiandocsocr/blob/main/document_processing/validation/mrz.py"
click node_repositories "https://github.com/protei300/russiandocsocr/blob/main/service/repositories/documents.py"
click node_store "https://github.com/protei300/russiandocsocr/blob/main/service/core/database.py"
click node_ports "https://github.com/protei300/russiandocsocr/tree/main/ports"
click node_settings "https://github.com/protei300/russiandocsocr/blob/main/service/core/storage_mode.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_web,node_browser toneBlue
class node_api,node_worker,node_runtime,node_transform toneAmber
class node_pipeline,node_quality,node_document,node_registration,node_fields,node_ocr,node_validation,node_ports toneMint
class node_repositories,node_store,node_settings toneRose
class node_operator toneIndigo
```

## Components

### Web client

- [Web interface](https://github.com/protei300/russiandocsocr/blob/main/web/src/App.vue): `web/src/App.vue`

### REST service

- [REST API](https://github.com/protei300/russiandocsocr/blob/main/service/api/documents.py): `service/api/documents.py`
- [Recognition worker](https://github.com/protei300/russiandocsocr/blob/main/service/worker.py): `service/worker.py`
- [ML runtime](https://github.com/protei300/russiandocsocr/blob/main/service/ml/runtime.py): `service/ml/runtime.py`
- [Result transform](https://github.com/protei300/russiandocsocr/blob/main/service/ml/transform.py): `service/ml/transform.py`

### Document processing

- [Recognition pipeline](https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline/pipeline.py): `document_processing/pipeline/pipeline.py`
- [Quality and fraud checks](https://github.com/protei300/russiandocsocr/tree/main/document_processing/pipeline_modules): `document_processing/pipeline_modules`
- [Document detection](https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/doc_detector/doc_detector.py): `document_processing/pipeline_modules/doc_detector/doc_detector.py`
- [Page registration](https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/page_registration/page_registration.py): `document_processing/pipeline_modules/page_registration/page_registration.py`
- [Field localization](https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/textfields_detector/textfields_detector.py): `document_processing/pipeline_modules/textfields_detector/textfields_detector.py`
- [OCR and correction](https://github.com/protei300/russiandocsocr/blob/main/document_processing/pipeline_modules/ocr_batch.py): `document_processing/pipeline_modules/ocr_batch.py`
- [MRZ validation](https://github.com/protei300/russiandocsocr/blob/main/document_processing/validation/mrz.py): `document_processing/validation/mrz.py`
- [Cross-language ports](https://github.com/protei300/russiandocsocr/tree/main/ports): `ports`

### Service state

- [Document repositories](https://github.com/protei300/russiandocsocr/blob/main/service/repositories/documents.py): `service/repositories/documents.py`
- [File-backed store](https://github.com/protei300/russiandocsocr/blob/main/service/core/database.py): `service/core/database.py`
- [Storage selection](https://github.com/protei300/russiandocsocr/blob/main/service/core/storage_mode.py): `service/core/storage_mode.py`

### Other components

- **Operator**
- **Browser user**

## Connections

- Browser user → Web interface: uses (evidence: `README.md`)
- Operator → REST API: uploads image (evidence: `README.md`)
- Web interface → REST API: calls REST (evidence: `README.md`)
- REST API → Recognition worker: queues recognition (evidence: `README.md`)
- Recognition worker → ML runtime: runs recognition (evidence: `service/worker.py`)
- ML runtime → Recognition pipeline: invokes pipeline
- Recognition pipeline → Quality and fraud checks: checks quality (evidence: `README.md`)
- Recognition pipeline → Document detection: detects document (evidence: `document_processing/pipeline/pipeline.py`)
- Recognition pipeline → Page registration: registers page (evidence: `README.md`)
- Recognition pipeline → Field localization: localizes fields (evidence: `README.md`)
- Recognition pipeline → OCR and correction: recognizes text (evidence: `README.md`)
- Recognition pipeline → MRZ validation: validates MRZ
- ML runtime → Result transform: formats results (evidence: `service/ml/runtime.py`)
- Recognition worker → Document repositories: reads and writes (evidence: `service/worker.py`)
- Document repositories → File-backed store: persists records
- Storage selection → File-backed store: selects backend (evidence: `service/core/storage_mode.py`)
- Operator → Cross-language ports: can use alternatives (evidence: `README.md`)
