# bhavesh-ahuja/ai-github-map architecture

> Architecture diagram of the GitHub repository bhavesh-ahuja/ai-github-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhavesh-ahuja/ai-github-map
- Repository: https://github.com/bhavesh-ahuja/ai-github-map

## Overview

##### Project type and purpose
- This is a full-stack web application (“AI GitHub Knowledge Map”) whose goal is to ingest GitHub repositories, build a knowledge graph, and surface AI-powered summaries and RAG (Retrieval-Augmented Generation) Q&A over that graph.

##### File structure
- Top-level:
– README.md (project overview)
– backend/ (Python service layer)
– frontend/ (React app with Vite)
- backend/:
– main.py (entry point, likely Flask/FastAPI server)
– services/file_service.py (file system operations, parsing)
– services/git_service.py (interacts with GitHub or git CLI)
- frontend/:
– package.json, vite.config.js (build tooling)
– src/ (React components, CSS, assets)
– public/, index.html (static assets)
- No obvious database folder—likely uses in-memory or external vector store/AI service.

##### README
- Feature callouts:
- Repository parsing → handled by file_service/git_service
- Knowledge Graph visualization → frontend graph component(s)
- AI-powered summaries & RAG Q&A → backend calls to LLM or vector database

##### Main components
a. Frontend (React + Vite)
- UI components (RepoInput, Sidebar, Graph View in Layout)
- HTTP client to backend API
b. Backend API (Python)
- main.py serving REST or WebSocket endpoints
- FileService for file I/O and code parsing
- GitService for cloning/fetching from GitHub
- AI/VectorService (external) for embeddings, RAG, summaries (implied)
c. External Services
- GitHub API (or git CLI)
- AI/LLM provider (OpenAI, Anthropic, etc.)
- Vector database or caching layer (e.g., Pinecone, Weaviate)
d. Data stores (if any)
- In-memory or file-based storage for knowledge graph
- Optional persisted store for embeddings

##### Relationships and interactions
- User → interacts with Frontend UI
- Frontend → sends HTTP requests (repo URL, query) to Backend API
- Backend API →
1. uses GitService to fetch/clone repository
2. uses FileService to parse files and build graph model
3. calls AI/VectorService for embeddings, indexing, summaries, Q&A
4. returns graph data or AI responses
- Frontend → renders graph, displays summaries, handles user queries

##### Architectural patterns & design principles
- Layered architecture: UI layer; application/API layer; service layer; external integrations.
- Separation of concerns: file parsing vs. git interactions vs. AI logic.
- Stateless backend processes each request, delegates to specialized services.
- Frontend as single-page application; backend as microservice/API.

##### Technologies, frameworks, libraries
- Frontend: React, Vite, ESLint, Axios/fetch
- Backend: Python (Flask or FastAPI), Pydantic (maybe), HTTP server
- External: GitHub REST API or git CLI; OpenAI SDK or similar; vector DB client

- Notes on protocols (HTTP/REST, WebSocket) and data formats (JSON, embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React + Vite SPA)"
        direction TB
        User["User Browser"]:::external
        App["App (UI Orchestration)"]:::frontend
        RepoInput["RepoInput Component"]:::frontend
        Sidebar["Sidebar Component"]:::frontend
        Layout["Layout (Graph View Container)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API Server (Python)"
        direction TB
        Main["main.py (REST API)"]:::backend
        GitSvc["GitService"]:::backend
        FileSvc["FileService"]:::backend
        AIService["AI/VectorService"]:::backend
    end

    %% External Services & Data Stores
    subgraph "External Services & Data Stores"
        direction TB
        GitHub["GitHub API"]:::external
        LLM["AI/LLM Provider"]:::external
        VectorDB["Vector Database"]:::datastore
    end

    %% Connections
    User -->|"visits SPA"| App
    App -->|"renders UI"| RepoInput
    App -->|"renders UI"| Sidebar
    App -->|"renders UI"| Layout
    Layout -->|"POST /parse-repo"| Main
    Main -->|"calls clone/fetch"| GitSvc
    Main -->|"calls parse files"| FileSvc
    Main -->|"requests embeddings/q&A"| AIService
    GitSvc -->|"clone/fetch via REST/CLI"| GitHub
    AIService -->|"embeddings & RAG"| LLM
    AIService -->|"store/retrieve embeddings"| VectorDB
    Main -->|"returns JSON data"| Layout

    %% Click Events
    click frontend "https://github.com/bhavesh-ahuja/ai-github-map/tree/main/frontend/"
    click RepoInput "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/frontend/src/components/RepoInput.jsx"
    click Sidebar "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/frontend/src/components/Sidebar.jsx"
    click Layout "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/frontend/src/components/Layout.jsx"
    click App "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/frontend/src/App.jsx"
    click App "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/frontend/src/main.jsx"
    click Main "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/backend/main.py"
    click FileSvc "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/backend/services/file_service.py"
    click GitSvc "https://github.com/bhavesh-ahuja/ai-github-map/blob/main/backend/services/git_service.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0288D1,color:#01579B
    classDef backend fill:#E8F5E9,stroke:#388E3C,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#F57C00,color:#E65100
    classDef datastore fill:#FFFDE7,stroke:#F9A825,color:#F57F17
```
