How jeffrin-jayan/training works
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: app.py Flask API · ai_engine.py AI engine · database.py Database · admin.py Admin
Components 23
Frontend
Streamlit user interface and shared UI helpers.
- Streamlit UI · User-facing app that renders citizen and admin workflows and calls the backend over HTTP.
frontend/app.py - UI helpers · Common frontend utilities and request wrappers used by the Streamlit app.
frontend/utils.py
Backend
Flask API, routes, and domain services.
- Flask API · Main backend composition point that wires config, database, routes, and startup behavior.
backend/app.py - Config · Backend configuration and environment settings.
backend/config.py - Database · SQLite access and persistence abstraction for application data.
backend/database.py - Seed data · Initial reference data population for schemes, offices, and demo flows.
backend/seed.py - Auth · Login, session, and role-gating endpoints.
backend/routes/auth.py - Dashboard · Citizen and admin overview data endpoints.
backend/routes/dashboard.py - Schemes · Scheme matching and comparison endpoints.
backend/routes/schemes.py - Chat · Conversational assistant and RAG-style Q&A endpoints.
backend/routes/chat.py - OCR · Document extraction and form autofill endpoints.
backend/routes/ocr.py - Complaints · Grievance letter generation endpoints.
backend/routes/complaints.py - Office finder · Service-center lookup and map data endpoints.
backend/routes/office_finder.py - PDF search · Circular and document retrieval endpoints.
backend/routes/pdf_search.py - Voice · Speech input and synthesis endpoints.
backend/routes/voice.py - Notifications · Alerts and reminder endpoints.
backend/routes/notifications.py - Admin · Admin analytics and document upload endpoints.
backend/routes/admin.py - AI engine · 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 · Persistent local database for schemes, offices, users, applications, and related records.
data/govassist.db
Ops
Containerization and testing entrypoints.
- Compose · Two-container deployment definition for backend and frontend services.
docker-compose.yml - Backend image · Docker image definition for the Flask backend.
backend/Dockerfile - Frontend image · Docker image definition for the Streamlit frontend.
frontend/Dockerfile - App tests · Main test entrypoint covering backend behavior and key flows.
tests/test_app.py
Connections 35
- 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.