# nikitakorotaevnikita-sudo/class-og-final architecture

> Architecture diagram of the GitHub repository nikitakorotaevnikita-sudo/class-og-final, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikitakorotaevnikita-sudo/class-og-final
- Repository: https://github.com/nikitakorotaevnikita-sudo/class-og-final

## Overview

This is a Russian citizen-appeals classification agent for the 59-FZ framework and official classifier, with Directum RX integration and operator review. Its main workflow accepts appeal text or an RX document, splits it into questions, retrieves classifier candidates, routes and classifies them, validates the result, then presents it for operator verification. The graph also captures configuration, audit feedback, and model-improvement capabilities. README details the classification stages; some subsystem wiring is inferred only where source excerpts are unavailable, so uncertain links are omitted.

Main entry points: [`src/api_server.py`](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/api_server.py) (Classification API), [`src/classifier_agent.py`](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py) (Candidate retrieval), [`src/rx_client.py`](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/rx_client.py) (RX document client), [`src/section_router.py`](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/section_router.py) (Section routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake and API"]
  node_api["Classification API<br/>[api_server.py]"]
  node_rxclient["RX document client<br/>[rx_client.py]"]
  node_extract["Text extraction<br/>[text_extractor.py]"]
end

subgraph group_classification["Classification"]
  node_segment["Question segmentation"]
  node_routing["Section routing<br/>[section_router.py]"]
  node_retrieval["Candidate retrieval"]
  node_index[("Classifier vector index<br/>[build_vectordb.py]")]
  node_reranker["Optional rerankers<br/>[reranker.py]"]
  node_llm["LLM classification"]
  node_llmservice["LLM provider client<br/>[integration_api.py]"]
  node_validation["Result validation"]
end

subgraph group_operations["Operator operations"]
  node_review["Operator review UI<br/>[app.js]"]
  node_verification["Verification API<br/>[api_server.py]"]
  node_appealslog[("Appeal audit log<br/>[appeals_logger.py]")]
  node_queue["Background job queue<br/>[job_queue.py]"]
  node_settings[("Runtime settings<br/>[settings_store.py]")]
end

subgraph group_learning["Data and improvement"]
  node_annotations[("Classifier annotations")]
  node_finetune["Model fine-tuning<br/>[auto_finetune.py]"]
  node_historical["Historical import"]
end

node_citizen(("Appeal submitter"))
node_operator(("Review operator"))
node_rx["Directum RX"]
node_provider["LLM provider"]

node_citizen -->|"submits appeal"| node_api
node_operator -->|"requests RX document"| node_api
node_api -->|"fetches document"| node_rxclient
node_rxclient -->|"reads document"| node_rx
node_rxclient -->|"extracts text"| node_extract
node_api -->|"classifies text"| node_segment
node_segment -->|"routes topics"| node_routing
node_segment -->|"retrieves per question"| node_retrieval
node_routing -->|"filters candidates"| node_retrieval
node_retrieval -->|"searches vectors"| node_index
node_retrieval -.->|"optionally reranks"| node_reranker
node_retrieval -->|"supplies candidates"| node_llm
node_llm -->|"requests classification"| node_llmservice
node_llmservice -->|"calls model"| node_provider
node_llm -->|"returns choices"| node_validation
node_validation -->|"returns validated result"| node_api
node_api -->|"serves result"| node_review
node_review -->|"presents alternatives"| node_operator
node_operator -->|"confirms or corrects"| node_verification
node_verification -->|"records verification"| node_appealslog
node_verification -.->|"saves annotation"| node_annotations
node_appealslog -.->|"supplies verified data"| node_finetune
node_api -.->|"dispatches jobs"| node_queue
node_api -->|"reads configuration"| node_settings
node_api -.->|"starts historical import"| node_historical

click node_api "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/api_server.py"
click node_rxclient "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/rx_client.py"
click node_extract "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/text_extractor.py"
click node_segment "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py"
click node_routing "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/section_router.py"
click node_retrieval "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py"
click node_index "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/build_vectordb.py"
click node_reranker "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/reranker.py"
click node_llm "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py"
click node_llmservice "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/integration_api.py"
click node_validation "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py"
click node_review "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/static/app.js"
click node_verification "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/api_server.py"
click node_appealslog "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/appeals_logger.py"
click node_queue "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/job_queue.py"
click node_settings "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/settings_store.py"
click node_annotations "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/annotations_storage.py"
click node_finetune "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/auto_finetune.py"
click node_historical "https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/auto_import_historical.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_api,node_rxclient,node_extract,node_operator toneBlue
class node_segment,node_routing,node_retrieval,node_index,node_reranker,node_llm,node_llmservice,node_validation toneAmber
class node_review,node_verification,node_appealslog,node_queue,node_settings toneMint
class node_annotations,node_finetune,node_historical toneRose
class node_citizen,node_rx,node_provider toneIndigo
```

## Components

### Intake and API

- [Classification API](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/api_server.py): `src/api_server.py`
- [RX document client](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/rx_client.py): `src/rx_client.py`
- [Text extraction](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/text_extractor.py): `src/text_extractor.py`

### Classification

- [Question segmentation](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py): `src/classifier_agent.py`
- [Section routing](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/section_router.py): `src/section_router.py`
- [Candidate retrieval](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py): `src/classifier_agent.py`
- [Classifier vector index](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/build_vectordb.py): `src/build_vectordb.py`
- [Optional rerankers](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/reranker.py): `src/reranker.py`
- [LLM classification](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py): `src/classifier_agent.py`
- [LLM provider client](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/integration_api.py): `src/integration_api.py`
- [Result validation](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/classifier_agent.py): `src/classifier_agent.py`

### Operator operations

- [Operator review UI](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/static/app.js): `src/static/app.js`
- [Verification API](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/api_server.py): `src/api_server.py`
- [Appeal audit log](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/appeals_logger.py): `src/appeals_logger.py`
- [Background job queue](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/job_queue.py): `src/job_queue.py`
- [Runtime settings](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/settings_store.py): `src/settings_store.py`

### Data and improvement

- [Classifier annotations](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/annotations_storage.py): `src/annotations_storage.py`
- [Model fine-tuning](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/auto_finetune.py): `src/auto_finetune.py`
- [Historical import](https://github.com/nikitakorotaevnikita-sudo/class-og-final/blob/main/src/auto_import_historical.py): `src/auto_import_historical.py`

### Other components

- **Appeal submitter**
- **Review operator**
- **Directum RX**
- **LLM provider**

## Connections

- Appeal submitter → Classification API: submits appeal
- Review operator → Classification API: requests RX document
- Classification API → RX document client: fetches document
- RX document client → Directum RX: reads document
- RX document client → Text extraction: extracts text
- Classification API → Question segmentation: classifies text
- Question segmentation → Section routing: routes topics
- Question segmentation → Candidate retrieval: retrieves per question
- Section routing → Candidate retrieval: filters candidates
- Candidate retrieval → Classifier vector index: searches vectors
- Candidate retrieval → Optional rerankers: optionally reranks
- Candidate retrieval → LLM classification: supplies candidates
- LLM classification → LLM provider client: requests classification
- LLM provider client → LLM provider: calls model
- LLM classification → Result validation: returns choices
- Result validation → Classification API: returns validated result
- Classification API → Operator review UI: serves result
- Operator review UI → Review operator: presents alternatives
- Review operator → Verification API: confirms or corrects
- Verification API → Appeal audit log: records verification
- Verification API → Classifier annotations: saves annotation
- Appeal audit log → Model fine-tuning: supplies verified data
- Classification API → Background job queue: dispatches jobs
- Classification API → Runtime settings: reads configuration
- Classification API → Historical import: starts historical import