# suchitabaral/open-budget-nepal architecture

> Architecture diagram of the GitHub repository suchitabaral/open-budget-nepal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suchitabaral/open-budget-nepal
- Repository: https://github.com/suchitabaral/open-budget-nepal

## Overview

1. **Repository shape**
   - This is a multi-app monorepo with three clear runtime boundaries:
     - `frontend/`: a React + Vite single-page app.
     - `backend/`: a TypeScript API server with a layered controller/service/route structure and Prisma persistence.
     - `rag_service/`: a Python FastAPI retrieval-augmented generation service.
   - `mof_extracted/` is the offline document corpus used by the RAG pipeline.

2. **Frontend: user-facing analytics and auth**
   - The frontend is organized around pages for `Dashboard`, `Insights`, `Watchdog`, `Chatbot`, `LoginPage`, `SignUpPage`, and `OTPVerificationPage`.
   - It has a reusable UI layer (`components/ui`), layout shell (`layout`), dashboard metric cards, and several chart components for budget visualization.
   - `src/data/` contains static/mock budget datasets, which suggests the UI can render meaningful analytics even before live API integration.

3. **Frontend data presentation boundary**
   - The dashboard/chart subsystem is primarily read-only presentation logic: it turns structured budget data into charts and summary cards.
   - Auth-related pages are isolated from the analytics views, indicating two user journeys: account access and budget exploration.
   - `Context/` exists as a separate state-management area, implying shared app state such as auth/session or UI preferences.

4. **Backend: application API layer**
   - The backend is a Node/TypeScript service with conventional separation into `routes`, `controllers`, `services`, `middleware`, `types`, and `utils`.
   - `Prisma` schema presence indicates the backend persists or queries application data through a database abstraction, though the exact database engine is not shown here.
   - This backend is the likely home for business rules around users, auth, and any non-RAG application data.

5. **Backend request flow**
   - Incoming HTTP requests are routed first through middleware, then into controllers, which delegate to services for the core logic.
   - Types and utility modules keep request/response handling consistent across the API.
   - The structure suggests the backend is intended to be the stable integration layer for the frontend rather than embedding business logic in the UI.

6. **RAG service: budget Q&A and semantic retrieval**
   - `rag_service/` is a separate FastAPI service dedicated to question answering over budget documents.
   - The README shows it exposes a health endpoint at `/api/v1/` and a chat endpoint at `/api/v1/chat`.
   - Its main role is to take a user query, retrieve relevant budget context, and generate an answer with an LLM.

7. **RAG infrastructure: vector store + local model**
   - The RAG service depends on Pinecone for vector search and Ollama for local model inference.
   - Environment configuration includes `PINECONE_API_KEY`, `PINECONE_INDEX_NAME`, `PINECONE_NAMESPACE`, `OLLAMA_BASE_URL`, and `OLLAMA_MODEL`.
   - This makes the architecture a hybrid of hosted retrieval infrastructure plus a locally served LLM.

8. **Ingestion pipeline and source corpus**
   - `rag_service/ingest.py` and the `mof_extracted/` directory indicate a preprocessing pipeline that converts Ministry of Finance source material into retrievable chunks.
   - The extracted tables and text files are the canonical knowledge base for the chatbot.
   - This ingestion step is a distinct offline boundary: document parsing/indexing happens before user queries are served.

9. **Deployment and runtime orchestration**
   - `docker-compose.yml` and `Dockerfile.rag` show containerized deployment for the RAG service and Ollama.
   - The README explicitly says the RAG service reaches Ollama over the Compose network via `http://ollama:11434`.
   - Ollama model storage is persisted in a Docker volume, so model download is a one-time setup cost.

10. **Probable end-to-end data flow**
   - For analytics views, the frontend renders budget data either from its local datasets or from the TypeScript backend API.
   - For chatbot queries, the frontend likely sends the user prompt to the backend or directly to the FastAPI RAG service, which retrieves relevant budget snippets from Pinecone and asks Ollama to generate the response.
   - The underlying knowledge comes from `mof_extracted`, not from live transaction data.

11. **Integration boundaries to keep in mind for a diagram**
   - Treat the frontend, backend API, and RAG service as separate deployable services.
   - Treat Pinecone as the retrieval index and Ollama as the generation engine.
   - Treat `mof_extracted/` as an offline source-data boundary feeding ingestion, not as a runtime database.

12. **Overall architecture summary**
   - The repo combines a budget-analytics web app with a dedicated document-question-answering service.
   - The UI is optimized for dashboards and user workflows, the backend handles app/API concerns, and the Python RAG stack handles semantic Q&A over extracted government budget documents.

Main entry points: [`frontend/src/components/layout/Layout.tsx`](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/components/layout/Layout.tsx) (Layout), [`rag_service/ingest.py`](https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/ingest.py) (Ingest), [`frontend/src/pages/Dashboard.tsx`](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Dashboard.tsx) (Dashboard), [`frontend/src/pages/Chatbot.tsx`](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Chatbot.tsx) (Chatbot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Shell<br/>React/Vite entry<br/>[main.tsx]"]
  node_frontend_layout["Layout<br/>UI shell<br/>[Layout.tsx]"]
  node_frontend_dashboard["Dashboard<br/>analytics page<br/>[Dashboard.tsx]"]
  node_frontend_insights["Insights<br/>analytics page<br/>[Insights.tsx]"]
  node_frontend_watchdog["Watchdog<br/>monitoring page<br/>[Watchdog.tsx]"]
  node_frontend_chatbot["Chatbot<br/>qa page<br/>[Chatbot.tsx]"]
  node_frontend_auth["Auth Pages<br/>access flow<br/>[LoginPage.tsx]"]
  node_frontend_state(("Context<br/>shared state"))
  node_frontend_charts["Charts<br/>visualization components"]
  node_frontend_data["Mock Data<br/>static datasets<br/>[budgetData.ts]"]
end

subgraph group_backend["Backend API"]
  node_backend_server["API Server<br/>Node/TS server<br/>[server.ts]"]
  node_backend_routes["Routes<br/>HTTP routing<br/>[index.ts]"]
  node_backend_middleware["Middleware<br/>request filters<br/>[index.ts]"]
  node_backend_controllers["Controllers<br/>request handlers<br/>[index.ts]"]
  node_backend_services["Services<br/>business logic<br/>[index.ts]"]
  node_backend_prisma["Prisma Schema<br/>persistence model<br/>[schema.prisma]"]
  node_backend_types["Types<br/>shared contracts<br/>[index.ts]"]
  node_backend_utils["Utils<br/>helpers<br/>[index.ts]"]
end

subgraph group_rag["RAG Service"]
  node_rag_api["FastAPI App<br/>Python service<br/>[main.py]"]
  node_rag_pipeline["RAG Core<br/>retrieval + generation<br/>[rag.py]"]
  node_rag_ingest["Ingest<br/>offline indexing<br/>[ingest.py]"]
end

subgraph group_offline["Offline Corpus"]
  node_corpus_text["Text Corpus<br/>source documents"]
  node_corpus_tables["Tables Corpus<br/>source tables"]
  node_corpus_translations["Translation Text<br/>source translation"]
end

subgraph group_infra["Runtime Infra"]
  node_pinecone[("Pinecone<br/>vector index")]
  node_ollama[("Ollama<br/>local LLM")]
  node_compose["Compose<br/>container orchestration<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"renders"| node_frontend_layout
node_frontend_layout -->|"hosts"| node_frontend_dashboard
node_frontend_layout -->|"hosts"| node_frontend_insights
node_frontend_layout -->|"hosts"| node_frontend_watchdog
node_frontend_layout -->|"hosts"| node_frontend_chatbot
node_frontend_layout -->|"hosts"| node_frontend_auth
node_frontend_dashboard -->|"uses"| node_frontend_charts
node_frontend_insights -->|"uses"| node_frontend_charts
node_frontend_watchdog -->|"reads"| node_frontend_data
node_frontend_dashboard -->|"reads"| node_frontend_data
node_frontend_chatbot -->|"shares state"| node_frontend_state
node_frontend_auth -->|"shares state"| node_frontend_state
node_frontend_app -.->|"calls API"| node_backend_server
node_frontend_chatbot -.->|"queries"| node_rag_api
node_backend_server -->|"passes through"| node_backend_middleware
node_backend_middleware -->|"forwards"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_controllers
node_backend_controllers -->|"delegates"| node_backend_services
node_backend_services -->|"persists via"| node_backend_prisma
node_backend_controllers -->|"uses"| node_backend_types
node_backend_services -->|"uses"| node_backend_utils
node_rag_api -->|"serves"| node_rag_pipeline
node_rag_pipeline -->|"retrieves from"| node_pinecone
node_rag_pipeline -->|"generates with"| node_ollama
node_rag_ingest -->|"ingests"| node_corpus_text
node_rag_ingest -->|"ingests"| node_corpus_tables
node_rag_ingest -->|"ingests"| node_corpus_translations
node_rag_ingest -->|"indexes"| node_pinecone
node_compose -->|"runs"| node_rag_api
node_compose -->|"runs"| node_ollama

click node_frontend_app "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/main.tsx"
click node_frontend_layout "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/components/layout/Layout.tsx"
click node_frontend_dashboard "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Dashboard.tsx"
click node_frontend_insights "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Insights.tsx"
click node_frontend_watchdog "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Watchdog.tsx"
click node_frontend_chatbot "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Chatbot.tsx"
click node_frontend_auth "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/LoginPage.tsx"
click node_frontend_state "https://github.com/suchitabaral/open-budget-nepal/tree/main/frontend/Context"
click node_frontend_charts "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/components/charts/RevenueBreakdownChart.tsx"
click node_frontend_data "https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/data/budgetData.ts"
click node_backend_server "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/server.ts"
click node_backend_routes "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/routes/index.ts"
click node_backend_middleware "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/middleware/index.ts"
click node_backend_controllers "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/controllers/index.ts"
click node_backend_services "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/services/index.ts"
click node_backend_prisma "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/prisma/schema.prisma"
click node_backend_types "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/types/index.ts"
click node_backend_utils "https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/utils/index.ts"
click node_rag_api "https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/main.py"
click node_rag_pipeline "https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/rag.py"
click node_rag_ingest "https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/ingest.py"
click node_corpus_text "https://github.com/suchitabaral/open-budget-nepal/blob/main/mof_extracted/text/source-book_kzajtb9.txt"
click node_corpus_tables "https://github.com/suchitabaral/open-budget-nepal/blob/main/mof_extracted/tables/source-book_kzajtb9_page10_table1.csv"
click node_corpus_translations "https://github.com/suchitabaral/open-budget-nepal/blob/main/mof_extracted/text/Budget Translation_2082-2083_nzrwuof.txt"
click node_compose "https://github.com/suchitabaral/open-budget-nepal/blob/main/docker-compose.yml"

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_layout,node_frontend_dashboard,node_frontend_insights,node_frontend_watchdog,node_frontend_chatbot,node_frontend_auth,node_frontend_state,node_frontend_charts,node_frontend_data toneBlue
class node_backend_server,node_backend_routes,node_backend_middleware,node_backend_controllers,node_backend_services,node_backend_prisma,node_backend_types,node_backend_utils toneAmber
class node_rag_api,node_rag_pipeline,node_rag_ingest toneMint
class node_corpus_text,node_corpus_tables,node_corpus_translations toneRose
class node_pinecone,node_ollama,node_compose toneIndigo
```

## Components

### Frontend

React + Vite single-page app for dashboards, auth, and chatbot entry points.

- [App Shell](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/main.tsx): React/Vite entry · Top-level SPA composition and client bootstrapping. · `frontend/src/main.tsx`
- [Layout](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/components/layout/Layout.tsx): UI shell · Shared navigation and page framing for the app. · `frontend/src/components/layout/Layout.tsx`
- [Dashboard](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Dashboard.tsx): analytics page · Main budget overview and summary view. · `frontend/src/pages/Dashboard.tsx`
- [Insights](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Insights.tsx): analytics page · Deeper analysis and breakdown view. · `frontend/src/pages/Insights.tsx`
- [Watchdog](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Watchdog.tsx): monitoring page · Alert-style budget monitoring and watchlist view. · `frontend/src/pages/Watchdog.tsx`
- [Chatbot](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/Chatbot.tsx): qa page · User-facing budget Q&A interface. · `frontend/src/pages/Chatbot.tsx`
- [Auth Pages](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/pages/LoginPage.tsx): access flow · Login, signup, and OTP verification journey. · `frontend/src/pages/LoginPage.tsx`
- [Context](https://github.com/suchitabaral/open-budget-nepal/tree/main/frontend/Context): shared state · App-wide state boundary for session and UI coordination. · `frontend/Context`
- [Charts](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/components/charts/RevenueBreakdownChart.tsx): visualization components · Reusable budget visualizations and metric presentation. · `frontend/src/components/charts/RevenueBreakdownChart.tsx`
- [Mock Data](https://github.com/suchitabaral/open-budget-nepal/blob/main/frontend/src/data/budgetData.ts): static datasets · Local budget and watchdog datasets used for read-only presentation. · `frontend/src/data/budgetData.ts`

### Backend API

TypeScript application API with layered request handling and Prisma persistence.

- [API Server](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/server.ts): Node/TS server · Backend runtime entrypoint that wires routes and middleware. · `backend/src/server.ts`
- [Routes](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/routes/index.ts): HTTP routing · Endpoint definitions and request dispatch. · `backend/src/routes/index.ts`
- [Middleware](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/middleware/index.ts): request filters · Cross-cutting request handling such as auth or validation. · `backend/src/middleware/index.ts`
- [Controllers](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/controllers/index.ts): request handlers · HTTP-level coordination between routes and services. · `backend/src/controllers/index.ts`
- [Services](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/services/index.ts): business logic · Core application rules and backend orchestration. · `backend/src/services/index.ts`
- [Prisma Schema](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/prisma/schema.prisma): persistence model · Database schema and persistence boundary for application data. · `backend/prisma/schema.prisma`
- [Types](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/types/index.ts): shared contracts · Shared TypeScript interfaces and DTO shapes. · `backend/src/types/index.ts`
- [Utils](https://github.com/suchitabaral/open-budget-nepal/blob/main/backend/src/utils/index.ts): helpers · Reusable backend helpers and support functions. · `backend/src/utils/index.ts`

### RAG Service

FastAPI service for retrieval-augmented question answering over budget documents.

- [FastAPI App](https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/main.py): Python service · RAG service entrypoint exposing health and chat endpoints. · `rag_service/main.py`
- [RAG Core](https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/rag.py): retrieval + generation · Query handling, retrieval orchestration, and answer generation. · `rag_service/rag.py`
- [Ingest](https://github.com/suchitabaral/open-budget-nepal/blob/main/rag_service/ingest.py): offline indexing · Document parsing and chunking pipeline for corpus indexing. · `rag_service/ingest.py`

### Offline Corpus

Extracted Ministry of Finance documents used to build the retrieval index.

- [Text Corpus](https://github.com/suchitabaral/open-budget-nepal/blob/main/mof_extracted/text/source-book_kzajtb9.txt): source documents · Extracted budget text used as canonical knowledge source. · `mof_extracted/text/source-book_kzajtb9.txt`
- [Tables Corpus](https://github.com/suchitabaral/open-budget-nepal/blob/main/mof_extracted/tables/source-book_kzajtb9_page10_table1.csv): source tables · Extracted budget tables used for retrieval and grounding. · `mof_extracted/tables/source-book_kzajtb9_page10_table1.csv`
- [Translation Text](https://github.com/suchitabaral/open-budget-nepal/blob/HEAD/mof_extracted/text/Budget%20Translation_2082-2083_nzrwuof.txt): source translation · Alternate language budget text used in the corpus. · `mof_extracted/text/Budget Translation_2082-2083_nzrwuof.txt`

### Runtime Infra

Containerized services and external dependencies used by the RAG stack.

- **Pinecone**: vector index · Hosted retrieval store for semantic search over budget chunks.
- **Ollama**: local LLM · Local model server used for generation during chat answers.
- [Compose](https://github.com/suchitabaral/open-budget-nepal/blob/main/docker-compose.yml): container orchestration · Container setup for the RAG service and local model runtime. · `docker-compose.yml`

## Connections

- App Shell → Layout: renders · SPA bootstraps the shared layout shell.
- Layout → Dashboard: hosts · Dashboard is one of the primary app views.
- Layout → Insights: hosts · Insights view shares the common shell.
- Layout → Watchdog: hosts · Watchdog view shares the common shell.
- Layout → Chatbot: hosts · Chatbot view shares the common shell.
- Layout → Auth Pages: hosts · Auth journey is separated but still uses app framing.
- Dashboard → Charts: uses · Dashboard depends on chart components for budget visualization.
- Insights → Charts: uses · Insights reuses chart components.
- Watchdog → Mock Data: reads · Watchdog can render from local watchdog datasets.
- Dashboard → Mock Data: reads · Dashboard can render from local budget datasets.
- Chatbot → Context: shares state · Chatbot and auth/session concerns likely use shared context.
- Auth Pages → Context: shares state · Authentication flow relies on shared app context.
- App Shell → API Server: calls API · Frontend integrates with the TypeScript backend for application data.
- Chatbot → FastAPI App: queries · Chat UI sends prompts to the RAG service directly or via backend.
- API Server → Middleware: passes through · Incoming requests are filtered through middleware.
- Middleware → Routes: forwards · Middleware hands requests to the routed API surface.
- Routes → Controllers: dispatches · Routes delegate to controllers.
- Controllers → Services: delegates · Controllers keep business logic in services.
- Services → Prisma Schema: persists via · Services use Prisma for application data access.
- Controllers → Types: uses · Controllers depend on shared request/response contracts.
- Services → Utils: uses · Services share helper logic through utilities.
- FastAPI App → RAG Core: serves · FastAPI endpoints invoke the retrieval/generation pipeline.
- RAG Core → Pinecone: retrieves from · Semantic search uses the vector index.
- RAG Core → Ollama: generates with · Answers are produced by the local LLM server.
- Ingest → Text Corpus: ingests · Offline pipeline parses the extracted text corpus.
- Ingest → Tables Corpus: ingests · Offline pipeline parses extracted tables.
- Ingest → Translation Text: ingests · Translation text is part of the indexed knowledge base.
- Ingest → Pinecone: indexes · Chunks are embedded and stored for retrieval.
- Compose → FastAPI App: runs · Compose orchestrates the RAG service container.
- Compose → Ollama: runs · Compose brings up the local model runtime.
