# binayakkoirala/kanun_gpt architecture

> Architecture diagram of the GitHub repository binayakkoirala/kanun_gpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/binayakkoirala/kanun_gpt
- Repository: https://github.com/binayakkoirala/kanun_gpt

## Overview

##### Project Type and Purpose
- Type: Full-stack AI-powered Q&A web application
- Purpose: Provide an interface for querying the Constitution of Nepal using a local Hugging Face–based chat model and a Chroma vector database of embeddings.

##### File Structure
- app.py – Flask web application that handles user requests, performs embedding lookups, invokes the language model, and returns responses.
- ingest.py – Preprocessing script: downloads/splits Constitution text, generates embeddings, and stores them in Chroma DB (stored/nepdata/chroma.sqlite3).
- stored/nepdata/chroma.sqlite3 – Local vector database storing document embeddings.
- templates/index.html – Single-page front-end for user input and display of answers.
- README.md – Describes the use of the “neural-chat-7b-v3-1.Q4_K_M.gguf” GGUF model and Chroma DB.

##### README for Additional Insights
- Model: TheBloke’s “neural-chat-7B-v3-1-GGUF” loaded locally.
- Database: Chroma vector store used to index Constitution segments.
- Framework: Flask is used to serve the UI and API endpoints.

##### Main Components and Their Interactions
A. Front-end (Browser)
– Index.html
– Sends user questions via HTTP POST to Flask.
B. Flask Back-end (app.py)
– HTTP API endpoint (/ask)
– Query embedding engine
– Context retrieval from Chroma
– Language model inference
– Response formatting
C. Vector Database (Chroma DB)
– SQLite file storing embeddings and metadata.
D. Embedding & Ingestion Pipeline (ingest.py)
– Constitution PDF downloader/splitter
– Embedding generation
– Data loading into Chroma DB
E. Language Model
– Locally hosted GGUF file loaded via Hugging Face-compatible loader (e.g., llama.cpp, transformers).

1. ingest.py → Chroma DB (populate embeddings)
2. Browser → Flask (/ask)
3. Flask → Embedding function (encode user query)
4. Embedding function → Chroma DB (retrieve top-k similar segments)
5. Flask → Language Model (send retrieved context + user query)
6. Language Model → Flask (generated answer)
7. Flask → Browser (HTTP response with answer)

##### Architectural Patterns and Principles
- Separation of concerns: ingestion vs. online serving
- Stateless web server: each request independently retrieves context, infers, and responds
- Local resource hosting: model and DB are file-based, no external cloud services
- Layered approach: Presentation → API → Retrieval → Inference → Persistence

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "One-time Setup"
        Ingestion["Ingestion Pipeline\ningest.py"]:::ml
        ChromaDB["Chroma DB\nchroma.sqlite3"]:::db
        Doc["README.md"]:::doc
        Ingestion -.->|"1.populate embeddings"|ChromaDB
    end

    subgraph "Runtime"
        Browser["Browser\nindex.html"]:::frontend
        Flask["Flask Back-end\napp.py"]:::backend
        Embedding["Embedding Function\n(chroma-sdk)"]:::ml
        Model["Language Model\nneural-chat-7B-v3"]:::ml

        Browser -->|"2.POST /ask"|Flask
        Flask -->|"3.encode query"|Embedding
        Embedding -->|"4.retrieve embeddings"|ChromaDB
        Flask -->|"5.send context+query"|Model
        Model -->|"6.generated answer"|Flask
        Flask -->|"7.HTTP response"|Browser
    end

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ml fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef doc fill:#FFFFE0,stroke:#000,stroke-width:1px

    click Browser "https://github.com/binayakkoirala/kanun_gpt/blob/main/templates/index.html"
    click Flask "https://github.com/binayakkoirala/kanun_gpt/blob/main/app.py"
    click Ingestion "https://github.com/binayakkoirala/kanun_gpt/blob/main/ingest.py"
    click ChromaDB "https://github.com/binayakkoirala/kanun_gpt/blob/main/stored/nepdata/chroma.sqlite3"
    click Doc "https://github.com/binayakkoirala/kanun_gpt/blob/main/README.md"
```
