# jeffrin-jayan/training architecture

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

- Interactive diagram: https://gitdiagram.com/jeffrin-jayan/training
- Repository: https://github.com/jeffrin-jayan/training

## Overview

1. **Overall shape**
   GovAssist AI is a two-tier monolith: a **Flask backend API** and a **Streamlit frontend**. The frontend is the only user-facing app; it calls the backend over HTTP for all data, AI, and workflow actions.

2. **Frontend boundary**
   `frontend/app.py` is the Streamlit entrypoint. It appears to orchestrate the citizen/admin UI, with `frontend/utils.py` holding shared UI helpers or request wrappers. The frontend does not own business logic; it renders results returned by the backend.

3. **Backend entrypoint and composition**
   `backend/app.py` is the Flask bootstrap. It wires together configuration, database initialization, route registration, and likely seed data loading. This is the main backend composition point for the whole system.

4. **API surface by domain**
   The backend is split into route modules under `backend/routes/`, each representing a functional subsystem:
   - `auth.py` for login/session/role gating
   - `dashboard.py` for citizen/admin overview data
   - `schemes.py` for scheme matching and comparison
   - `chat.py` for conversational assistant and RAG-style Q&A
   - `ocr.py` for document extraction and form autofill
   - `complaints.py` for grievance letter generation
   - `office_finder.py` for service-center lookup/map data
   - `pdf_search.py` for circular/document retrieval
   - `voice.py` for speech input/output
   - `notifications.py` for alerts or reminders
   - `admin.py` for admin analytics and document upload

5. **Core AI and retrieval layer**
   `backend/ai_engine.py` is the main intelligence layer. Based on the README, it likely centralizes scheme scoring/matching, conversational responses, PDF search/RAG, OCR post-processing, complaint drafting, and voice-related helpers. This is the main domain layer beneath the route handlers.

6. **Persistence layer**
   `backend/database.py` encapsulates SQLite access through SQLAlchemy. The repository includes a prebuilt database at `data/govassist.db`, so the app has a persistent local data store for schemes, offices, users, applications, and possibly uploaded artifacts or indexes.

7. **Initialization and seed data**
   `backend/seed.py` likely populates default reference data such as welfare schemes, office locations, and possibly demo users. This matters architecturally because the app depends on known baseline data to make the demo flows work immediately after startup.

8. **Data flow from UI to backend**
   Typical requests flow as: **Streamlit interaction → backend route → AI/business layer → database or retrieval engine → JSON/result payload → UI rendering**. Some flows also return derived outputs such as comparison tables, extracted OCR fields, generated complaint text, map markers, or audio content.

9. **AI/search infrastructure**
   The README indicates the backend uses **FAISS** and **sentence transformers** for retrieval over policy PDFs/circulars, plus **EasyOCR** for scan extraction, **gTTS** for speech synthesis, and **SpeechRecognition** for voice input. These are not separate services; they are embedded capabilities inside the backend AI layer.

10. **Security and role separation**
   The app distinguishes at least two roles: **citizen** and **admin**. Auth and authorization boundaries appear in `routes/auth.py` and `routes/admin.py`, with admin-specific features like analytics and PDF uploads separated from the citizen-facing workflows.

11. **Deployment topology**
   `docker-compose.yml` and the two Dockerfiles indicate the system is deployed as **two containers**: one for Flask and one for Streamlit. SQLite keeps the persistence local and lightweight, which fits the demo-oriented, single-node architecture.

12. **Testing and quality boundary**
   `tests/test_app.py` is the main test entrypoint and likely covers route behavior, database rules, and mocked AI flows. This suggests the repo emphasizes integrated backend behavior rather than isolated microservice contracts.

13. **What to show in an architecture diagram**
   A clear diagram should center on:
   **Streamlit UI** on the left, **Flask API** in the middle, **AI engine + route modules** as backend internals, and **SQLite / FAISS-backed document retrieval / uploaded PDFs** as the data foundation. Admin and citizen flows should branch from the same backend, not separate systems.

Main entry points: [`backend/app.py`](https://github.com/jeffrin-jayan/training/blob/main/backend/app.py) (Flask API), [`backend/ai_engine.py`](https://github.com/jeffrin-jayan/training/blob/main/backend/ai_engine.py) (AI engine), [`backend/database.py`](https://github.com/jeffrin-jayan/training/blob/main/backend/database.py) (Database), [`backend/routes/admin.py`](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/admin.py) (Admin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Streamlit UI<br/>streamlit entrypoint<br/>[app.py]"]
  node_frontend_utils["UI helpers<br/>shared frontend helpers<br/>[utils.py]"]
end

subgraph group_backend["Backend"]
  node_backend_app["Flask API<br/>backend bootstrap<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_database[("Database<br/>sqlalchemy sqlite layer<br/>[database.py]")]
  node_backend_seed["Seed data<br/>bootstrap data<br/>[seed.py]"]
  node_route_auth["Auth<br/>route module<br/>[auth.py]"]
  node_route_dashboard["Dashboard<br/>route module<br/>[dashboard.py]"]
  node_route_schemes["Schemes<br/>route module<br/>[schemes.py]"]
  node_route_chat["Chat<br/>route module<br/>[chat.py]"]
  node_route_ocr["OCR<br/>route module<br/>[ocr.py]"]
  node_route_complaints["Complaints<br/>route module<br/>[complaints.py]"]
  node_route_office["Office finder<br/>route module<br/>[office_finder.py]"]
  node_route_pdf["PDF search<br/>route module<br/>[pdf_search.py]"]
  node_route_voice["Voice<br/>route module<br/>[voice.py]"]
  node_route_notifications["Notifications<br/>route module<br/>[notifications.py]"]
  node_route_admin["Admin<br/>route module<br/>[admin.py]"]
  node_ai_engine{{"AI engine<br/>domain intelligence<br/>[ai_engine.py]"}}
end

subgraph group_data["Data"]
  node_local_db[("govassist.db<br/>sqlite data store<br/>[govassist.db]")]
end

subgraph group_ops["Ops"]
  node_docker_compose["Compose<br/>deployment spec<br/>[docker-compose.yml]"]
  node_backend_docker["Backend image<br/>container build"]
  node_frontend_docker["Frontend image<br/>container build"]
  node_tests_app["App tests<br/>integration tests<br/>[test_app.py]"]
end

node_frontend_app -->|"uses"| node_frontend_utils
node_frontend_app -->|"HTTP calls"| node_backend_app
node_backend_app -->|"loads"| node_backend_config
node_backend_app -->|"initializes"| node_backend_database
node_backend_app -->|"seeds"| node_backend_seed
node_backend_app -->|"registers"| node_route_auth
node_backend_app -->|"registers"| node_route_dashboard
node_backend_app -->|"registers"| node_route_schemes
node_backend_app -->|"registers"| node_route_chat
node_backend_app -->|"registers"| node_route_ocr
node_backend_app -->|"registers"| node_route_complaints
node_backend_app -->|"registers"| node_route_office
node_backend_app -->|"registers"| node_route_pdf
node_backend_app -->|"registers"| node_route_voice
node_backend_app -->|"registers"| node_route_notifications
node_backend_app -->|"registers"| node_route_admin
node_route_auth -->|"reads/writes"| node_backend_database
node_route_dashboard -->|"derives"| node_ai_engine
node_route_schemes -->|"scores"| node_ai_engine
node_route_chat -->|"answers"| node_ai_engine
node_route_ocr -->|"extracts"| node_ai_engine
node_route_complaints -->|"drafts"| node_ai_engine
node_route_office -->|"queries"| node_backend_database
node_route_pdf -->|"retrieves"| node_ai_engine
node_route_voice -->|"transforms"| node_ai_engine
node_route_notifications -->|"reads/writes"| node_backend_database
node_route_admin -->|"administers"| node_backend_database
node_route_admin -->|"analyzes"| node_ai_engine
node_ai_engine -->|"consults"| node_backend_database
node_ai_engine -->|"stores"| node_local_db
node_backend_database -->|"backed by"| node_local_db
node_docker_compose -->|"builds"| node_backend_docker
node_docker_compose -->|"builds"| node_frontend_docker
node_tests_app -->|"exercises"| node_backend_app
node_tests_app -.->|"mocks/checks"| node_ai_engine

click node_frontend_app "https://github.com/jeffrin-jayan/training/blob/main/frontend/app.py"
click node_frontend_utils "https://github.com/jeffrin-jayan/training/blob/main/frontend/utils.py"
click node_backend_app "https://github.com/jeffrin-jayan/training/blob/main/backend/app.py"
click node_backend_config "https://github.com/jeffrin-jayan/training/blob/main/backend/config.py"
click node_backend_database "https://github.com/jeffrin-jayan/training/blob/main/backend/database.py"
click node_backend_seed "https://github.com/jeffrin-jayan/training/blob/main/backend/seed.py"
click node_route_auth "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/auth.py"
click node_route_dashboard "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/dashboard.py"
click node_route_schemes "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/schemes.py"
click node_route_chat "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/chat.py"
click node_route_ocr "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/ocr.py"
click node_route_complaints "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/complaints.py"
click node_route_office "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/office_finder.py"
click node_route_pdf "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/pdf_search.py"
click node_route_voice "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/voice.py"
click node_route_notifications "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/notifications.py"
click node_route_admin "https://github.com/jeffrin-jayan/training/blob/main/backend/routes/admin.py"
click node_ai_engine "https://github.com/jeffrin-jayan/training/blob/main/backend/ai_engine.py"
click node_local_db "https://github.com/jeffrin-jayan/training/blob/main/data/govassist.db"
click node_docker_compose "https://github.com/jeffrin-jayan/training/blob/main/docker-compose.yml"
click node_backend_docker "https://github.com/jeffrin-jayan/training/tree/main/backend/Dockerfile"
click node_frontend_docker "https://github.com/jeffrin-jayan/training/tree/main/frontend/Dockerfile"
click node_tests_app "https://github.com/jeffrin-jayan/training/blob/main/tests/test_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_frontend_app,node_frontend_utils toneBlue
class node_backend_app,node_backend_config,node_backend_database,node_backend_seed,node_route_auth,node_route_dashboard,node_route_schemes,node_route_chat,node_route_ocr,node_route_complaints,node_route_office,node_route_pdf,node_route_voice,node_route_notifications,node_route_admin,node_ai_engine toneAmber
class node_local_db toneMint
class node_docker_compose,node_backend_docker,node_frontend_docker,node_tests_app toneRose
```

## Components

### Frontend

Streamlit user interface and shared UI helpers.

- [Streamlit UI](https://github.com/jeffrin-jayan/training/blob/main/frontend/app.py): streamlit entrypoint · User-facing app that renders citizen and admin workflows and calls the backend over HTTP. · `frontend/app.py`
- [UI helpers](https://github.com/jeffrin-jayan/training/blob/main/frontend/utils.py): shared frontend helpers · Common frontend utilities and request wrappers used by the Streamlit app. · `frontend/utils.py`

### Backend

Flask API, routes, and domain services.

- [Flask API](https://github.com/jeffrin-jayan/training/blob/main/backend/app.py): backend bootstrap · Main backend composition point that wires config, database, routes, and startup behavior. · `backend/app.py`
- [Config](https://github.com/jeffrin-jayan/training/blob/main/backend/config.py): runtime config · Backend configuration and environment settings. · `backend/config.py`
- [Database](https://github.com/jeffrin-jayan/training/blob/main/backend/database.py): sqlalchemy sqlite layer · SQLite access and persistence abstraction for application data. · `backend/database.py`
- [Seed data](https://github.com/jeffrin-jayan/training/blob/main/backend/seed.py): bootstrap data · Initial reference data population for schemes, offices, and demo flows. · `backend/seed.py`
- [Auth](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/auth.py): route module · Login, session, and role-gating endpoints. · `backend/routes/auth.py`
- [Dashboard](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/dashboard.py): route module · Citizen and admin overview data endpoints. · `backend/routes/dashboard.py`
- [Schemes](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/schemes.py): route module · Scheme matching and comparison endpoints. · `backend/routes/schemes.py`
- [Chat](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/chat.py): route module · Conversational assistant and RAG-style Q&A endpoints. · `backend/routes/chat.py`
- [OCR](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/ocr.py): route module · Document extraction and form autofill endpoints. · `backend/routes/ocr.py`
- [Complaints](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/complaints.py): route module · Grievance letter generation endpoints. · `backend/routes/complaints.py`
- [Office finder](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/office_finder.py): route module · Service-center lookup and map data endpoints. · `backend/routes/office_finder.py`
- [PDF search](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/pdf_search.py): route module · Circular and document retrieval endpoints. · `backend/routes/pdf_search.py`
- [Voice](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/voice.py): route module · Speech input and synthesis endpoints. · `backend/routes/voice.py`
- [Notifications](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/notifications.py): route module · Alerts and reminder endpoints. · `backend/routes/notifications.py`
- [Admin](https://github.com/jeffrin-jayan/training/blob/main/backend/routes/admin.py): route module · Admin analytics and document upload endpoints. · `backend/routes/admin.py`
- [AI engine](https://github.com/jeffrin-jayan/training/blob/main/backend/ai_engine.py): domain intelligence · Core intelligence layer for matching, chat, retrieval, OCR post-processing, drafting, and voice helpers. · `backend/ai_engine.py`

### Data

Persistent store and local artifacts.

- [govassist.db](https://github.com/jeffrin-jayan/training/blob/main/data/govassist.db): sqlite data store · Persistent local database for schemes, offices, users, applications, and related records. · `data/govassist.db`

### Ops

Containerization and testing entrypoints.

- [Compose](https://github.com/jeffrin-jayan/training/blob/main/docker-compose.yml): deployment spec · Two-container deployment definition for backend and frontend services. · `docker-compose.yml`
- [Backend image](https://github.com/jeffrin-jayan/training/tree/main/backend/Dockerfile): container build · Docker image definition for the Flask backend. · `backend/Dockerfile`
- [Frontend image](https://github.com/jeffrin-jayan/training/tree/main/frontend/Dockerfile): container build · Docker image definition for the Streamlit frontend. · `frontend/Dockerfile`
- [App tests](https://github.com/jeffrin-jayan/training/blob/main/tests/test_app.py): integration tests · Main test entrypoint covering backend behavior and key flows. · `tests/test_app.py`

## Connections

- Streamlit UI → UI helpers: uses · Streamlit app relies on shared helpers and request wrappers.
- Streamlit UI → Flask API: HTTP calls · Frontend sends all workflow requests to the backend API.
- Flask API → Config: loads · Backend bootstrap reads runtime configuration.
- Flask API → Database: initializes · Backend wires persistence during startup.
- Flask API → Seed data: seeds · Startup may load baseline reference data.
- Flask API → Auth: registers · Flask app mounts authentication routes.
- Flask API → Dashboard: registers · Flask app mounts dashboard routes.
- Flask API → Schemes: registers · Flask app mounts scheme matching routes.
- Flask API → Chat: registers · Flask app mounts assistant routes.
- Flask API → OCR: registers · Flask app mounts OCR routes.
- Flask API → Complaints: registers · Flask app mounts complaint-generation routes.
- Flask API → Office finder: registers · Flask app mounts office lookup routes.
- Flask API → PDF search: registers · Flask app mounts document search routes.
- Flask API → Voice: registers · Flask app mounts voice routes.
- Flask API → Notifications: registers · Flask app mounts notification routes.
- Flask API → Admin: registers · Flask app mounts admin routes.
- Auth → Database: reads/writes · Authentication persists and checks user/session state.
- Dashboard → AI engine: derives · Dashboard aggregates backend-generated status and summary data.
- Schemes → AI engine: scores · Scheme routes delegate matching and comparison logic.
- Chat → AI engine: answers · Chat routes use the intelligence layer for RAG and response generation.
- OCR → AI engine: extracts · OCR routes use post-processing and document understanding helpers.
- Complaints → AI engine: drafts · Complaint routes generate grievance text with AI assistance.
- Office finder → Database: queries · Office lookup uses stored location/reference data.
- PDF search → AI engine: retrieves · PDF search routes delegate semantic retrieval to the AI layer.
- Voice → AI engine: transforms · Voice routes use speech input and speech synthesis helpers.
- Notifications → Database: reads/writes · Notification state and delivery metadata are persisted.
- Admin → Database: administers · Admin functions access application data and uploaded artifacts.
- Admin → AI engine: analyzes · Admin analytics may rely on derived intelligence outputs.
- AI engine → Database: consults · Intelligence layer uses persisted reference and user data.
- AI engine → govassist.db: stores · Persistent local SQLite database backs core workflows.
- Database → govassist.db: backed by · SQLAlchemy access layer persists to the local database file.
- Compose → Backend image: builds · Compose defines the backend container.
- Compose → Frontend image: builds · Compose defines the frontend container.
- App tests → Flask API: exercises · Tests target backend endpoints and integrated behavior.
- App tests → AI engine: mocks/checks · Tests likely validate the AI-backed flows.