# abhishek-aditya-bs/codegraph architecture

> Architecture diagram of the GitHub repository abhishek-aditya-bs/codegraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishek-aditya-bs/codegraph
- Repository: https://github.com/abhishek-aditya-bs/codegraph

## Overview

##### Project type and purpose
- CodeGraph is a full-stack “GraphRAG Codebase Analysis System.”
- It consists of a Streamlit-based frontend UI, a Python backend that handles ingestion, graph building, vector embedding, and a Neo4j graph database.
- It integrates with external services (OpenAI for embeddings & LLM, GitHub or local file system for code ingestion).

##### File structure
- Top-level:
- app/ – business logic and Streamlit UI
- docker/ – Dockerfile, Compose, prerequisite checks
- assets/ – demo gif
- tests/ – unit & integration test suites
- requirements.txt, pytest.ini, run_tests.py
- app/:
- main.py – Streamlit UI with workflow tabs
- config.py – env and CLI configuration
- database.py – Neo4j connection & session management
- ingestion.py – code parsing & chunking
- graph_builder.py – knowledge graph creation
- query_processor.py – GraphRAG hybrid query logic
- utilities/ – file, folder, git, LLM, Neo4j helper modules

##### README insights
- Describes a 3-layer architecture: Structural (knowledge graph), Semantic (vector embeddings), Bridge (integration).
- Workflow: Input → Ingestion → Knowledge Graph → Vector Index → Query Interface → Database Management.
- Dependencies: Streamlit, Neo4j, OpenAI API, Python 3.10+, Docker.

##### Detail
- How utilities (git_utils, file_utils, llm_utils) are invoked by ingestion or query services.
- Docker Compose network: CodeGraph ↔ Neo4j.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    DOCOMP["Docker Compose"]:::infra
    DOCKERFILE["Dockerfile (App Container)"]:::infra
    DOCOMP -->|orchestrates| DOCKERFILE
    DOCOMP -->|orchestrates| NEODB

    %% Application Containers
    subgraph "CodeGraph App Container"
        direction TB
        UI["Streamlit UI"]:::ui
        CONFIG["Configuration Module"]:::service
        subgraph "Backend Services"
            direction TB
            INGEST["Ingestion Service"]:::service
            BUILDER["Graph Builder Service"]:::service
            EMBED["Embedding Service"]:::service
            QUERY["Query Processor Service"]:::service
            DBCONN["Database Connector"]:::service
            subgraph "Utilities"
                direction TB
                FUTIL["File Utilities"]:::util
                FOLDUTIL["Folder Utilities"]:::util
                GITUTIL["Git Utilities"]:::util
                GSU["Graph Statistics Utils"]:::util
                NEOUTIL["Neo4j Utilities"]:::util
            end
        end
    end

    %% External Services
    CODESRC["GitHub/Local File System"]:::external
    OPENAI["OpenAI API"]:::external

    %% Persistence
    NEODB["Neo4j Graph Database"]:::db

    %% User Interaction Flow
    UI -->|"trigger ingestion/query"| INGEST
    UI -->|queries| QUERY

    %% Ingestion Flow
    INGEST -->|"read code"| CODESRC
    INGEST -->|"use file_utils"| FUTIL
    INGEST -->|"use folder_utils"| FOLDUTIL
    INGEST -->|"use git_utils"| GITUTIL
    INGEST -->|"output chunks"| BUILDER

    %% Graph Building Flow
    BUILDER -->|"create nodes/relationships"| NEODB
    BUILDER -->|"use neo4j_utils"| NEOUTIL

    %% Embedding Flow
    EMBED -->|"send chunks"| OPENAI
    EMBED -->|"receive embeddings"| EMBED
    EMBED -->|"write embeddings"| NEODB

    %% Query Flow
    QUERY -->|"cypher/vector search"| NEODB
    QUERY -->|"optional llm call"| OPENAI
    QUERY -->|"use llm_utils"| EMBED

    %% Configuration
    CONFIG -->|loads env/cli| UI
    CONFIG -->|provides config| INGEST
    CONFIG -->|provides config| BUILDER
    CONFIG -->|provides config| EMBED
    CONFIG -->|provides config| QUERY
    CONFIG -->|provides config| DBCONN

    %% DB Connector
    DBCONN -->|"manage session"| NEODB
    DBCONN -->|"use neo4j_utils"| NEOUTIL

    %% Docker Compose Dependencies
    DOCKERFILE -->|builds app| UI
    DOCKERFILE -->|builds app| INGEST
    DOCKERFILE -->|builds app| BUILDER
    DOCKERFILE -->|builds app| EMBED
    DOCKERFILE -->|builds app| QUERY
    DOCKERFILE -->|builds app| DBCONN

    %% Click Events
    click UI "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/main.py"
    click CONFIG "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/config.py"
    click DBCONN "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/database.py"
    click INGEST "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/ingestion.py"
    click BUILDER "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/graph_builder.py"
    click QUERY "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/query_processor.py"
    click EMBED "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/utilities/llm_utils.py"
    click FUTIL "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/utilities/file_utils.py"
    click FOLDUTIL "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/utilities/folder_utils.py"
    click GITUTIL "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/utilities/git_utils.py"
    click GSU "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/utilities/graph_stats_utils.py"
    click NEOUTIL "https://github.com/abhishek-aditya-bs/codegraph/blob/main/app/utilities/neo4j_utils.py"
    click DOCOMP "https://github.com/abhishek-aditya-bs/codegraph/blob/main/docker/docker-compose.yml"
    click DOCKERFILE "https://github.com/abhishek-aditya-bs/codegraph/tree/main/docker/Dockerfile"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef service fill:#E6FFEA,stroke:#28A745,color:#22863A;
    classDef util fill:#FFF5E1,stroke:#DBAB09,color:#735C0F;
    classDef db fill:#FFE6E6,stroke:#CB2431,color:#B31D28;
    classDef external fill:#F0E6FF,stroke:#6F42C1,color:#5A32A3;
    classDef infra fill:#E8F0FE,stroke:#1B1F23,color:#24292F;
```
