# mohdsaadma07/code-sense architecture

> Architecture diagram of the GitHub repository mohdsaadma07/code-sense, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohdsaadma07/code-sense
- Repository: https://github.com/mohdsaadma07/code-sense

## Overview

This is a **single-service FastAPI backend** that implements a **local Retrieval-Augmented Generation (RAG)** workflow:

- **Inputs**: local text files (upload) + public GitHub repos (URL)
- **Processing**: chunking → embeddings (HuggingFace `all-MiniLM-L6-v2`) → storage in **FAISS**
- **Query modes**:
- **Similarity search** (raw retrieval)
- **RAG answer generation** using a **local Llama GGUF model** via `llama-cpp-python`

##### Entry point & composition
- `code-app/app/main.py`: FastAPI app creation + router registration (composition root)
- `code-app/app/config.py`: environment/config (e.g., `.env`, GitHub token, paths)

##### API layer (controllers)
- `code-app/app/routes/ingest.py`: local file ingestion endpoints
- `code-app/app/routes/github.py`: GitHub ingestion endpoints
- `code-app/app/routes/query.py`: similarity search endpoints
- `code-app/app/routes/llama.py`: RAG query endpoints

##### Domain / data contracts
- `code-app/app/models/document.py`: Pydantic models for request/response + document/chunk structures

##### Service layer (core logic)
- `code-app/app/services/embeddings.py`: embedding model initialization + embedding calls
- `code-app/app/services/storage.py`: FAISS index management + persistence to disk
- `code-app/app/services/rag.py`: retrieval orchestration + prompt context assembly (core RAG logic)
- `code-app/app/services/llama_rag.py`: Llama inference wrapper / RAG execution with local LLM
- `code-app/app/services/github_loader.py`: GitHub API interaction + repository file traversal + content extraction
- `code-app/app/services/github.py`: likely higher-level GitHub ingestion coordination (depends on repo structure)

##### Storage / artifacts (infrastructure)
- `vectorstore/index.faiss` + `vectorstore/index.pkl`: persisted FAISS index + metadata
- `.env`: optional token + config

Include:
- **User / Client** (Swagger UI, curl, any HTTP client)
- **Code-Sense FastAPI Service**
- **GitHub (external system)** (GitHub API / raw content)
- **Local Disk** (vectorstore persistence + model file)

- Client → FastAPI (HTTP)
- FastAPI → GitHub (HTTPS, optional auth token)
- FastAPI ↔ Local Disk (read/write FAISS index + read model file)
- (Optionally) FastAPI → HuggingFace model runtime (logical dependency; it runs locally but conceptually an “embedding subsystem”)

##### Ingestion: local file (`/ingest/`)
`Client -> routes/ingest.py -> services (chunking) -> services/embeddings.py -> services/storage.py -> FAISS index on disk`

- Explicitly show **Text Splitter** (`RecursiveCharacterTextSplitter`) as a sub-component inside ingestion flow.

##### Ingestion: GitHub (`/github/ingest`)
`Client -> routes/github.py -> services/github.py -> services/github_loader.py -> (GitHub API) -> extracted text -> splitter -> embeddings -> storage -> FAISS on disk`

- GitHub token from `.env` going into GitHub loader as configuration (optional path).

##### Query: similarity (`/query/`)
`Client -> routes/query.py -> services/embeddings.py (embed query) -> services/storage.py (similarity search) -> results`

##### Query: RAG + Llama (`/llama/query`)
`Client -> routes/llama.py -> services/rag.py (retrieve top-k chunks) -> services/llama_rag.py (prompt + inference) -> local Llama GGUF -> response`

- Make it visually clear that **retrieval** happens *before* LLM generation and that the **context chunks** are injected into the prompt.

- **Layered architecture**: Routes → Services → Storage/External systems
- **Pipeline pattern** for ingestion: parse → split → embed → index
- **RAG pattern** for answering: embed query → retrieve → augment prompt → generate
- **Local-first privacy**: LLM inference and vector store are on local disk (no hosted LLM)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (Level 1)
    %% =========================
    Client["Client (Swagger UI / curl / HTTP)"]:::external

    subgraph LocalRuntime["Local Machine / Runtime"]
        FastAPI["Code-Sense FastAPI Service"]:::system
        Disk["Local Disk"]:::infra
    end

    GitHubAPI["GitHub API / Raw Content (Rate limits)"]:::external

    Client -->|"HTTP requests"| FastAPI
    FastAPI -->|"HTTPS fetch repo files (optional auth)"| GitHubAPI
    FastAPI <-->|"read/write persisted artifacts"| Disk

    %% =========================
    %% FastAPI Service Internals (Level 2/3)
    %% =========================
    subgraph FastAPIApp["FastAPI Application (Single Service)"]
        direction TB

        Main["main.py<br/>(FastAPI app creation + router registration)"]:::compose
        Config["config.py<br/>(.env, paths, GITHUB_TOKEN)"]:::config
        Domain["document.py<br/>(Pydantic request/response models,<br/>Document + Chunk contracts)"]:::model

        subgraph APILayer["API Layer (Routes)"]
            direction TB
            RouteIngest["routes/ingest.py<br/>Local file ingestion API"]:::route
            RouteGitHub["routes/github.py<br/>GitHub ingestion API"]:::route
            RouteQuery["routes/query.py<br/>Similarity search API"]:::route
            RouteLlama["routes/llama.py<br/>RAG + Llama query API"]:::route
        end

        subgraph ServiceLayer["Service Layer (Business Logic)"]
            direction TB

            Splitter["Text Splitter<br/>(RecursiveCharacterTextSplitter)"]:::service
            Embeddings["embeddings.py<br/>Embeddings (all-MiniLM-L6-v2)"]:::ml
            Storage["storage.py<br/>FAISS index mgmt + persistence"]:::storage
            GitHubSvc["github.py<br/>GitHub ingestion coordinator"]:::service
            GitHubLoader["github_loader.py<br/>GitHub API traversal + extraction"]:::service
            Rag["rag.py<br/>Retrieve top-k + assemble context"]:::service
            LlamaRag["llama_rag.py<br/>llama-cpp-python inference wrapper"]:::ml
        end

        %% Logical runtime components (local)
        EmbedRuntime["SentenceTransformers / HuggingFace runtime<br/>(all-MiniLM-L6-v2)"]:::ml
        LlamaRuntime["Local Llama GGUF runtime<br/>(via llama-cpp-python)"]:::ml
    end

    %% =========================
    %% Storage / Artifacts
    %% =========================
    subgraph LocalArtifacts["Local Artifacts (Persistence)"]
        direction TB
        FaissMem[("FAISS In-Memory Index")]:::storage
        FaissDisk[("FAISS Persisted Index<br/>vectorstore/index.faiss + vectorstore/index.pkl")]:::infra
        GGUF[["Local Llama Model Artifact<br/>Llama-3.2-1B-Instruct-F16.gguf"]]:::infra
        EnvFile[[".env<br/>(GITHUB_TOKEN optional)"]]:::infra
    end

    %% =========================
    %% Composition + wiring
    %% =========================
    Main -->|"register routers"| RouteIngest
    Main -->|"register routers"| RouteGitHub
    Main -->|"register routers"| RouteQuery
    Main -->|"register routers"| RouteLlama

    Config -->|"config values"| RouteGitHub
    Config -->|"GITHUB_TOKEN (optional)"| GitHubLoader
    EnvFile -->|"loaded into config"| Config

    Domain -->|"request/response contracts"| RouteIngest
    Domain -->|"request/response contracts"| RouteGitHub
    Domain -->|"request/response contracts"| RouteQuery
    Domain -->|"request/response contracts"| RouteLlama

    %% =========================
    %% Flow 1: Local file ingestion (/ingest/)
    %% =========================
    RouteIngest -->|"upload text"| Splitter
    Splitter -->|"split into chunks"| Embeddings
    Embeddings -->|"compute embeddings"| EmbedRuntime
    Embeddings -->|"vectors"| Storage
    Storage -->|"upsert vectors + metadata"| FaissMem
    Storage -->|"persist index"| FaissDisk
    Disk <-->|"store/reload index"| FaissDisk

    %% =========================
    %% Flow 2: GitHub ingestion (/github/ingest)
    %% =========================
    RouteGitHub -->|"ingest repo URL"| GitHubSvc
    GitHubSvc -->|"fetch + extract text"| GitHubLoader
    GitHubLoader -->|"HTTPS calls (rate-limited)"| GitHubAPI
    GitHubLoader -->|"extracted text"| Splitter

    %% =========================
    %% Flow 3: Similarity search (/query/)
    %% =========================
    RouteQuery -->|"query text"| Embeddings
    Embeddings -->|"embed query"| EmbedRuntime
    RouteQuery -->|"kNN search"| Storage
    Storage -->|"similarity search"| FaissMem
    Storage -->|"load index if needed"| FaissDisk
    Storage -->|"top-k chunks"| RouteQuery

    %% =========================
    %% Flow 4: RAG + Llama (/llama/query)
    %% =========================
    RouteLlama -->|"question"| Embeddings
    Embeddings -->|"embed query"| EmbedRuntime
    RouteLlama -->|"retrieve top-k"| Rag
    Rag -->|"kNN search"| Storage
    Storage -->|"top-k context chunks"| Rag
    Rag -->|"compose prompt<br/>(context injection)"| LlamaRag
    LlamaRag -->|"infer (local)"| LlamaRuntime
    LlamaRuntime -->|"read GGUF"| GGUF
    Disk -->|"read model file"| GGUF
    LlamaRag -->|"RAG answer"| RouteLlama

    %% =========================
    %% Click Events (mapped components)
    %% =========================
    click Main "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/main.py"
    click Config "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/config.py"

    click RouteIngest "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/routes/ingest.py"
    click RouteGitHub "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/routes/github.py"
    click RouteQuery "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/routes/query.py"
    click RouteLlama "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/routes/llama.py"

    click Domain "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/models/document.py"

    click Embeddings "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/services/embeddings.py"
    click Storage "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/services/storage.py"
    click Rag "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/services/rag.py"
    click LlamaRag "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/services/llama_rag.py"
    click GitHubSvc "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/services/github.py"
    click GitHubLoader "https://github.com/mohdsaadma07/code-sense/blob/main/code-app/app/services/github_loader.py"

    %% =========================
    %% Styles
    %% =========================
    classDef system fill:#0b3d91,stroke:#062a63,color:#ffffff,stroke-width:2px
    classDef compose fill:#1456c0,stroke:#0b3d91,color:#ffffff,stroke-width:2px
    classDef config fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:2px

    classDef route fill:#2f81f7,stroke:#0b3d91,color:#ffffff,stroke-width:1.5px
    classDef service fill:#2da44e,stroke:#1a7f37,color:#ffffff,stroke-width:1.5px
    classDef storage fill:#238636,stroke:#1a7f37,color:#ffffff,stroke-width:1.5px

    classDef ml fill:#f59e0b,stroke:#b45309,color:#111827,stroke-width:1.5px
    classDef model fill:#7c3aed,stroke:#5b21b6,color:#ffffff,stroke-width:1.5px

    classDef infra fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.5px
    classDef external fill:#a855f7,stroke:#6b21a8,color:#ffffff,stroke-width:1.5px
```
