# falkordb/code-graph-backend architecture

> Architecture diagram of the GitHub repository falkordb/code-graph-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/falkordb/code-graph-backend
- Repository: https://github.com/falkordb/code-graph-backend

## Overview

##### Project Type and Purpose
- This is a RESTful source-code analysis service (Flask API) that inspects local code folders (Python/C/Java), builds a graph representation using FalkorDB (a graph database), and exposes endpoints for querying and exploring that graph. It also provides simple static UI assets and integrates optional LLM-based code completion and git-history utils.

##### Top-Level Structure & Architectural Patterns
- “api/” holds the backend service:
- index.py – Flask app entrypoint (routes & wsgi)
- analyzers/ – language-specific code parsers (Python, C, Java) plus a generic analyzer wrapper
- code_coverage/ – LCOV parser to attach coverage metadata
- git_utils/ – git-history graph builder
- llm.py & prompts.py – optional LLM integration for auto-completion
- project.py, info.py – orchestration & metadata endpoints
- “static/index.html” – client-side landing page (minimal UI)
- Dockerfile, .github/workflows – containerization and CI/CD (build/test/release)
- Tests cover endpoints, analyzers, graph operations, and git utils.

a. Clients & Entry Points
- REST Clients (curl, Postman)
- Web UI (static/index.html served or external code-graph UI)
- Third-party tools (GraphRAG-SDK, FalkorDB Browser)
b. API Layer (Flask Service)
- HTTP server hosting routes (/analyze_folder, /list_repos, /get_neighbors, etc.)
- Authentication via SECRET_TOKEN from .env
c. Business Logic Modules
- Analyzers: parse source files → produce graph entities
- Git Utils: read git history → enrich graph
- Code Coverage: parse .lcov → annotate nodes/edges
- LLM Module: generate completions or semantic queries
d. Data Layer
- FalkorDB Graph Database (cloud or local Redis-based)
- Python client library (api/project.py) writes/reads graph data
e. Deployment & CI
- Docker container runs Flask + Python dependencies (requirements.txt / pyproject.toml)
- GitHub Actions: lint, test, build and publish Docker images
- Vercel config for static hosting if applicable

##### Relationships & Data Flows
1. Client → HTTP(S) → Flask API
2. Flask routes dispatch → Business Logic Modules
3. Analyzers & git_utils read the file system / git repo
4. Modules emit graph entities → Graph DB write operations
5. Client queries graph endpoints → Flask reads from Graph DB → JSON responses
6. Optional: LLM module queries Graph DB + prompts → returns completions

##### Highlighted Design Principles
- Single-responsibility per analyzer (one language each)
- Clear separation: API layer vs. business modules vs. data persistence
- Configurable: .env template driving secrets, FalkorDB endpoint, ports
- Extensible: plug new analyzers or LLM backends via api/analyzers and api/llm

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients/UI Layer
    RESTClients["REST Clients"]:::clients
    WebUI["Web UI\n(static/index.html)"]:::clients
    ThirdParty["Third-party Tools\n(GraphRAG-SDK,\nFalkorDB Browser)"]:::clients

    %% Backend Infrastructure
    subgraph "Docker Container\n(Flask Analysis Service)" 
        direction TB
        Index["api/index.py\n(Flask Entrypoint)"]:::api
        GraphRoutes["api/graph.py"]:::api
        ProjectRoutes["api/project.py"]:::api
        InfoRoutes["api/info.py"]:::api

        subgraph "Analyzers" 
            direction TB
            SourceAnalyzer["api/analyzers/source_analyzer.py"]:::api
            AnalyzerBase["api/analyzers/analyzer.py"]:::api
            PythonAnalyzer["api/analyzers/python/analyzer.py"]:::api
            CAnalyzer["api/analyzers/c/analyzer.py"]:::api
            JavaAnalyzer["api/analyzers/java/analyzer.py"]:::api
        end

        CodeCoverage["api/code_coverage/lcov/lcov.py"]:::api
        GitUtils["api/git_utils/git_utils.py"]:::api
        GitGraph["api/git_utils/git_graph.py"]:::api

        AutoComplete["api/auto_complete.py"]:::api
        LLM["api/llm.py"]:::api
        Prompts["api/prompts.py"]:::api

        subgraph "Entities" 
            direction TB
            EntityModel["api/entities/entity.py"]:::api
            FileEntity["api/entities/file.py"]:::api
            EntityEncoder["api/entities/entity_encoder.py"]:::api
        end
    end

    %% Data Layer
    GraphDB["FalkorDB Graph DB\n(cylinder)"]:::datastore
    FalkorCloud["FalkorDB Cloud"]:::external

    %% CI/CD & Deployment
    GitHubActions["GitHub Actions"]:::external
    DockerHub["Docker Hub"]:::external
    Vercel["Vercel\n(static hosting)"]:::external

    %% Project & Config
    EnvTemplate[".env.template"]:::api
    Dockerfile["Dockerfile"]:::api
    Pyproject["pyproject.toml"]:::api
    Requirements["requirements.txt"]:::api
    Tests["tests/"]:::api

    %% Connections: Clients to API
    RESTClients -->|POST /analyze_folder| Index
    WebUI -->|HTTP GET| Index
    ThirdParty -->|SDK/API Calls| Index

    %% Routing
    Index -->|dispatch| GraphRoutes
    Index -->|dispatch| ProjectRoutes
    Index -->|dispatch| InfoRoutes

    %% Business Logic invocations
    GraphRoutes -->|uses| SourceAnalyzer
    GraphRoutes -->|uses| AnalyzerBase
    SourceAnalyzer -->|delegates| PythonAnalyzer
    SourceAnalyzer -->|delegates| CAnalyzer
    SourceAnalyzer -->|delegates| JavaAnalyzer

    ProjectRoutes -->|uses| GitUtils
    ProjectRoutes -->|uses| GitGraph

    InfoRoutes -->|uses| CodeCoverage

    GraphRoutes -->|optional| AutoComplete
    AutoComplete -->|calls| LLM
    LLM -->|uses| Prompts

    %% Entities and DB
    GraphRoutes -->|produces entities| EntityModel
    ProjectRoutes -->|produces entities| EntityModel
    EntityModel -->|writes/reads| GraphDB
    FileEntity -->|written to| GraphDB
    EntityEncoder -->|encodes JSON| GraphRoutes

    %% External DB
    GraphDB -->|replicates| FalkorCloud

    %% CI/CD flows
    GitHubActions -->|build/test| Tests
    GitHubActions -->|build image| Dockerfile
    GitHubActions -->|publish| DockerHub
    DockerHub -->|deploy| DockerContainer
    Vercel -->|hosts| WebUI

    %% Click events
    click Index "https://github.com/falkordb/code-graph-backend/blob/main/api/index.py"
    click GraphRoutes "https://github.com/falkordb/code-graph-backend/blob/main/api/graph.py"
    click ProjectRoutes "https://github.com/falkordb/code-graph-backend/blob/main/api/project.py"
    click InfoRoutes "https://github.com/falkordb/code-graph-backend/blob/main/api/info.py"
    click SourceAnalyzer "https://github.com/falkordb/code-graph-backend/blob/main/api/analyzers/source_analyzer.py"
    click AnalyzerBase "https://github.com/falkordb/code-graph-backend/blob/main/api/analyzers/analyzer.py"
    click PythonAnalyzer "https://github.com/falkordb/code-graph-backend/blob/main/api/analyzers/python/analyzer.py"
    click CAnalyzer "https://github.com/falkordb/code-graph-backend/blob/main/api/analyzers/c/analyzer.py"
    click JavaAnalyzer "https://github.com/falkordb/code-graph-backend/blob/main/api/analyzers/java/analyzer.py"
    click CodeCoverage "https://github.com/falkordb/code-graph-backend/blob/main/api/code_coverage/lcov/lcov.py"
    click GitUtils "https://github.com/falkordb/code-graph-backend/blob/main/api/git_utils/git_utils.py"
    click GitGraph "https://github.com/falkordb/code-graph-backend/blob/main/api/git_utils/git_graph.py"
    click AutoComplete "https://github.com/falkordb/code-graph-backend/blob/main/api/auto_complete.py"
    click LLM "https://github.com/falkordb/code-graph-backend/blob/main/api/llm.py"
    click Prompts "https://github.com/falkordb/code-graph-backend/blob/main/api/prompts.py"
    click EntityModel "https://github.com/falkordb/code-graph-backend/blob/main/api/entities/entity.py"
    click FileEntity "https://github.com/falkordb/code-graph-backend/blob/main/api/entities/file.py"
    click EntityEncoder "https://github.com/falkordb/code-graph-backend/blob/main/api/entities/entity_encoder.py"
    click WebUI "https://github.com/falkordb/code-graph-backend/blob/main/static/index.html"
    click EnvTemplate "https://github.com/falkordb/code-graph-backend/blob/main/.env.template"
    click Dockerfile "https://github.com/falkordb/code-graph-backend/tree/main/Dockerfile"
    click GitHubActions "https://github.com/falkordb/code-graph-backend/blob/main/.github/workflows/python-app.yml"
    click GitHubActions "https://github.com/falkordb/code-graph-backend/blob/main/.github/workflows/release-image.yml"
    click Pyproject "https://github.com/falkordb/code-graph-backend/blob/main/pyproject.toml"
    click Requirements "https://github.com/falkordb/code-graph-backend/blob/main/requirements.txt"
    click Tests "https://github.com/falkordb/code-graph-backend/tree/main/tests/"

    %% Styles
    classDef clients fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef api fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#FFD0D0,stroke:#333,stroke-width:1px
```
