How suchitabaral/open-budget-nepal works
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: Layout.tsx Layout · ingest.py Ingest · Dashboard.tsx Dashboard · Chatbot.tsx Chatbot
Components 27
Frontend
React + Vite single-page app for dashboards, auth, and chatbot entry points.
- App Shell · Top-level SPA composition and client bootstrapping.
frontend/src/main.tsx - Layout · Shared navigation and page framing for the app.
frontend/src/components/layout/Layout.tsx - Dashboard · Main budget overview and summary view.
frontend/src/pages/Dashboard.tsx - Insights · Deeper analysis and breakdown view.
frontend/src/pages/Insights.tsx - Watchdog · Alert-style budget monitoring and watchlist view.
frontend/src/pages/Watchdog.tsx - Chatbot · User-facing budget Q&A interface.
frontend/src/pages/Chatbot.tsx - Auth Pages · Login, signup, and OTP verification journey.
frontend/src/pages/LoginPage.tsx - Context · App-wide state boundary for session and UI coordination.
frontend/Context - Charts · Reusable budget visualizations and metric presentation.
frontend/src/components/charts/RevenueBreakdownChart.tsx - Mock Data · 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 · Backend runtime entrypoint that wires routes and middleware.
backend/src/server.ts - Routes · Endpoint definitions and request dispatch.
backend/src/routes/index.ts - Middleware · Cross-cutting request handling such as auth or validation.
backend/src/middleware/index.ts - Controllers · HTTP-level coordination between routes and services.
backend/src/controllers/index.ts - Services · Core application rules and backend orchestration.
backend/src/services/index.ts - Prisma Schema · Database schema and persistence boundary for application data.
backend/prisma/schema.prisma - Types · Shared TypeScript interfaces and DTO shapes.
backend/src/types/index.ts - Utils · 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 · RAG service entrypoint exposing health and chat endpoints.
rag_service/main.py - RAG Core · Query handling, retrieval orchestration, and answer generation.
rag_service/rag.py - Ingest · 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 · Extracted budget text used as canonical knowledge source.
mof_extracted/text/source-book_kzajtb9.txt - Tables Corpus · Extracted budget tables used for retrieval and grounding.
mof_extracted/tables/source-book_kzajtb9_page10_table1.csv - Translation Text · 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 · Hosted retrieval store for semantic search over budget chunks.
- Ollama · Local model server used for generation during chat answers.
- Compose · Container setup for the RAG service and local model runtime.
docker-compose.yml
Connections 30
- 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.