# sylphai-inc/githubchat architecture

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

- Interactive diagram: https://gitdiagram.com/sylphai-inc/githubchat
- Repository: https://github.com/sylphai-inc/githubchat

## Overview

##### What this project is (type + purpose)
**GithubChat** is a **RAG (Retrieval-Augmented Generation) assistant** that lets a user “chat with” an arbitrary GitHub repository.

Architecturally it’s a **hybrid full-stack** project with **two possible UIs**:
- **React + Vite frontend** (`frontend/`) that talks to a **FastAPI backend** (`api.py`)
- A **Streamlit UI** (`app.py`) that likely talks to the same RAG core directly (or could call the FastAPI, depending on implementation)

The “core” backend logic lives in `src/`:
- `src/data_pipeline.py`: ingest repo → chunk/index → persist/reload (DatabaseManager)
- `src/rag.py`: orchestrates “prepare repo + retrieve + generate answer” lifecycle (RAG class)

External dependencies implied by README:
- **OpenAI API** (via `OPENAI_API_KEY`) for embeddings and/or generation
- **GitHub** as the upstream content source (repo URL)

##### How to read the file tree as architecture hints
Top-level:
- `api.py` → **FastAPI HTTP entrypoint** (serves `/query`)
- `app.py` → **Streamlit entrypoint** (interactive UI, separate runtime)
- `config.py` → config management (keys, model params, paths)
- `src/` → backend domain logic (RAG + pipeline)
- `frontend/` → React UI (Vite, Tailwind)
- `tests/test_rag.py` → confirms `RAG` is a first-class unit (core component)

Frontend details:
- `frontend/src/components/GitHubChat.tsx` → key UI component (calls `/query`)
- Vite config + Tailwind → typical SPA build pipeline

Backend details:
- `src/data_pipeline.py` (DatabaseManager) strongly suggests:
- some **persistent store** (vector DB, sqlite, local files, etc.)
- “prepare repo, persist from reloading” (README) → there’s a **cache/index reuse** path
- `src/rag.py` → the orchestrator that API/Streamlit call into

##### React Web App (Vite)
- `frontend/src/App.tsx`
- `frontend/src/components/GitHubChat.tsx`
- Talks to FastAPI: `POST /query`

##### Streamlit App
- `app.py`
- Calls RAG core (direct import) *or* calls FastAPI (show whichever is true in code; if unknown, show both paths but mark one as “likely”)

##### FastAPI Server
- `api.py`
- Endpoint: `POST /query` taking `{ repo_url, query }` returning `{ rationale, answer, contexts }`

##### RAG Orchestrator
- `src/rag.py` (`RAG` class)
- “Repo readiness check / load existing index”
- “Retrieve contexts”
- “Prompt + generate answer”
- “Return rationale + contexts + answer”

##### Data Pipeline / Index Manager
- `src/data_pipeline.py` (`DatabaseManager`)
- Responsibilities:
- Fetch/parse repo content
- Chunking / preprocessing
- Embedding computation (likely)
- Persist and reload index

##### Config
- `config.py` + `.streamlit/secrets.toml` (runtime secrets)
- As a cross-cutting dependency feeding API/Streamlit/RAG (model name, paths, API keys)

##### GitHub (External)
- Input: `repo_url`
- Data: repo files, README, code

##### Vector Store / Index Persistence (Local or DB)
- Not explicitly named in tree, but README says “persist from reloading”
- “Embeddings + chunks + metadata”
- “Repo fingerprint / commit hash” (if implemented)
- “local disk / sqlite / chroma / etc.” once confirmed

##### LLM / Embeddings Provider (OpenAI)
- External API called by RAG pipeline
- Two logical calls:
- embeddings (indexing + maybe query embedding)
- chat/completions (answer generation)

##### RAG → DatabaseManager
- If repo not indexed: “prepare_repo(repo_url)” → triggers fetch/chunk/embed/persist
- Else: “load_index(repo_url)” → reuse persisted store

##### Alternate flow (Streamlit)
- If Streamlit instead calls FastAPI, show Streamlit → FastAPI like the React path.

##### Architectural patterns/design principles to call out
- **Separation of concerns**
- UI (React/Streamlit) vs API (FastAPI) vs Core (`src/`) vs Storage/External
- **RAG lifecycle split**
- *Ingestion/indexing* (`DatabaseManager`) vs *Query-time retrieval+generation* (`RAG`)
- **Caching/persistence**
- Key feature: “persist from reloading” → important stateful component (vector store/index) even if the service is stateless
- **Plug-in/external provider boundary**

**Labels**
- Use exact names from repo where possible: `RAG`, `DatabaseManager`, `POST /query`, `GitHubChat.tsx`
- Responses: `answer`, `rationale`, `contexts`

- Clients (blue): React, Streamlit
- Services (green): FastAPI
- Core modules (teal): RAG, DatabaseManager
- External services (gray): GitHub, OpenAI

##### Checklist of project-specific details not to miss
- Two entrypoints: `api.py` and `app.py` (must both appear)
- `/query` contract (must label request/response fields)
- Persistence/caching concept (vector store/index reuse)
- OpenAI key management via `.streamlit/secrets.toml` + `config.py`
- That the “repo URL” drives a **data ingestion pipeline** prior to retrieval

- exact storage technology (Chroma/FAISS/sqlite/files)
- whether ingestion is triggered per-request or via an explicit “prepare” step
- whether repo cloning uses git, GitHub API, or raw HTTP fetches

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% =========================
  %% Diagram 1: Runtime / Deployment (C4-ish Container View)
  %% =========================
  subgraph D1["Diagram 1 - Runtime / Deployment View"]
    direction TB

    subgraph D1Clients["Client Layer"]
      direction TB
      U["User"]:::external

      subgraph D1Web["Browser (React + Vite SPA :3000)"]
        direction TB
        FEApp["React App (App.tsx)"]:::frontend
        FEChat["GitHubChat UI (GitHubChat.tsx)"]:::frontend
      end

      ST["Streamlit App (:8501)"]:::frontend
    end

    subgraph D1Services["Service Layer"]
      direction TB
      API["FastAPI Service (:8000)\nPOST /query"]:::service
      RAGC["RAG Core (RAG)"]:::core
      DBC["Data Pipeline (DatabaseManager)"]:::core
    end

    subgraph D1Data["Data + External Layer"]
      direction TB
      VS[("Vector Store / Persisted Index\n(embeddings + chunks + metadata)")]:::datastore
      GH["GitHub (External)\nRepo contents"]:::external
      OA["OpenAI API (External)\nEmbeddings + Chat/Completions"]:::external
      CFG["Config + Secrets\n(config.py + secrets.toml)"]:::config
    end

    %% Primary (React -> FastAPI)
    U -->|"enter repo_url + query"| FEChat
    FEChat -->|"render via"| FEApp
    FEApp -->|"HTTP POST /query\n{repo_url, query}"| API
    API -->|"call RAG.query(repo_url, query)"| RAGC

    %% RAG lifecycle
    RAGC -->|"index if missing / load if exists"| DBC
    DBC -->|"fetch repo files"| GH
    DBC -->|"embed chunks (indexing)"| OA
    DBC -->|"persist/load index"| VS
    RAGC -->|"retrieve topK contexts"| VS
    RAGC -->|"prompt w/contexts + query\n(generate answer)"| OA
    RAGC -->|"return {rationale, answer, contexts}"| API
    API -->|"JSON {rationale, answer, contexts}"| FEApp

    %% Alternate (Streamlit)
    U -->|"enter repo_url + query"| ST
    ST -->|"direct call (likely)\nRAG.query(repo_url, query)"| RAGC
    ST -.->|"alternate: HTTP POST /query"| API

    %% Config/secrets (cross-cutting)
    CFG -->|"model params / paths / API keys"| API
    CFG -->|"model params / paths / API keys"| ST
    CFG -->|"provider settings"| RAGC
    CFG -->|"storage settings"| DBC
  end

  %% =========================
  %% Diagram 2: Backend Component View (C4-ish Component View)
  %% =========================
  subgraph D2["Diagram 2 - Backend Component View (src/ + entrypoints)"]
    direction TB

    subgraph D2Entrypoints["Entrypoints / Transport"]
      direction TB
      API2["api.py\nFastAPI Controller\nPOST /query"]:::service
      ST2["app.py\nStreamlit UI"]:::frontend
      CFG2["config.py\nConfiguration Management"]:::config
      SECR[".streamlit/secrets.toml\nRuntime Secrets"]:::config
    end

    subgraph D2Core["Core Domain (src/)"]
      direction TB
      RAG2["src/rag.py\nRAG Orchestrator (RAG)"]:::core

      subgraph D2Pipeline["src/data_pipeline.py\nIndexing + Persistence (DatabaseManager)"]
        direction TB
        DBM["DatabaseManager"]:::core
        LOADER["GitHub Loader\n(fetch/parse repo)"]:::core
        CHUNK["Chunker / Preprocessor\n(split into chunks)"]:::core
        EMB["Embedder\n(calls OpenAI embeddings)"]:::core
        VSAD["VectorStore Adapter\n(persist/reload/retrieve)"]:::core
      end

      PKG["src/__init__.py\nPackage Init"]:::core
    end

    subgraph D2StoresExt["Stores + External Dependencies"]
      direction TB
      VS2[("Persisted Index / Vector Store")]:::datastore
      GH2["GitHub (External)"]:::external
      OA2["OpenAI API (External)"]:::external
    end

    subgraph D2Tests["Tests"]
      direction TB
      TINIT["tests/__init__.py"]:::test
      TRAG["tests/test_rag.py\nRAG Unit/Integration Tests"]:::test
    end

    %% Transport -> Core
    API2 -->|"validate request\n{repo_url, query}"| RAG2
    ST2 -->|"direct call (likely)"| RAG2
    ST2 -.->|"alternate: HTTP call"| API2

    %% RAG orchestration responsibilities
    RAG2 -->|"ensure index ready\n(load or build)"| DBM
    RAG2 -->|"retrieve contexts"| VSAD
    RAG2 -->|"generate answer\n(prompt + contexts)"| OA2

    %% Pipeline internals
    DBM -->|"fetch repo"| LOADER
    LOADER -->|"repo content"| CHUNK
    CHUNK -->|"chunks"| EMB
    EMB -->|"vectors"| VSAD

    %% Storage + external
    LOADER -->|"HTTPS / Git access"| GH2
    EMB -->|"embeddings API"| OA2
    VSAD -->|"persist / load / search"| VS2

    %% Config + secrets
    SECR -->|"OPENAI_API_KEY etc."| CFG2
    CFG2 -->|"settings"| API2
    CFG2 -->|"settings"| ST2
    CFG2 -->|"settings"| RAG2
    CFG2 -->|"settings"| DBM

    %% Tests -> Core
    TRAG -->|"exercise RAG behaviors"| RAG2
    TINIT -->|"package init"| TRAG
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click FEApp "https://github.com/sylphai-inc/githubchat/blob/master/frontend/src/App.tsx"
  click FEChat "https://github.com/sylphai-inc/githubchat/blob/master/frontend/src/components/GitHubChat.tsx"
  click D1Web "https://github.com/sylphai-inc/githubchat/tree/master/frontend/"
  click API "https://github.com/sylphai-inc/githubchat/blob/master/api.py"
  click API2 "https://github.com/sylphai-inc/githubchat/blob/master/api.py"
  click ST "https://github.com/sylphai-inc/githubchat/blob/master/app.py"
  click ST2 "https://github.com/sylphai-inc/githubchat/blob/master/app.py"
  click RAGC "https://github.com/sylphai-inc/githubchat/blob/master/src/rag.py"
  click RAG2 "https://github.com/sylphai-inc/githubchat/blob/master/src/rag.py"
  click DBC "https://github.com/sylphai-inc/githubchat/blob/master/src/data_pipeline.py"
  click DBM "https://github.com/sylphai-inc/githubchat/blob/master/src/data_pipeline.py"
  click CFG "https://github.com/sylphai-inc/githubchat/blob/master/config.py"
  click CFG2 "https://github.com/sylphai-inc/githubchat/blob/master/config.py"
  click SECR "https://github.com/sylphai-inc/githubchat/blob/master/.streamlit/secrets.toml"
  click PKG "https://github.com/sylphai-inc/githubchat/blob/master/src/__init__.py"
  click TRAG "https://github.com/sylphai-inc/githubchat/blob/master/tests/test_rag.py"
  click TINIT "https://github.com/sylphai-inc/githubchat/blob/master/tests/__init__.py"

  %% =========================
  %% Styles
  %% =========================
  classDef frontend fill:#1e88e5,stroke:#0d47a1,stroke-width:1.5px,color:#ffffff
  classDef service fill:#2e7d32,stroke:#1b5e20,stroke-width:1.5px,color:#ffffff
  classDef core fill:#00897b,stroke:#004d40,stroke-width:1.5px,color:#ffffff
  classDef datastore fill:#fb8c00,stroke:#e65100,stroke-width:1.5px,color:#1b1b1b
  classDef external fill:#9e9e9e,stroke:#424242,stroke-width:1.5px,color:#111111
  classDef config fill:#6a1b9a,stroke:#4a148c,stroke-width:1.5px,color:#ffffff
  classDef test fill:#c2185b,stroke:#880e4f,stroke-width:1.5px,color:#ffffff
```
