# redfox1899/gitunderstand architecture

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

- Interactive diagram: https://gitdiagram.com/redfox1899/gitunderstand
- Repository: https://github.com/redfox1899/gitunderstand

## Overview

##### Project type and purpose
- From the file tree and minimal README, we see:
- A `src/api` folder with routers (ingest, summary, health) and middleware ⇒ a web/API server (likely FastAPI).
- A `templates` folder plus `static/js` ⇒ server-rendered frontend with client-side scripts.
- A `core` package with modules for cloning, chunking, parsing, AI summarization, formatting, and ingestion ⇒ business-logic layer that processes Git repositories and generates AI-powered summaries.
- A `storage` package supporting local and GCS backends ⇒ pluggable persistence layer.
- Docker, Docker Compose, CI/CD workflows ⇒ containerized full-stack application with automated deployment.
- Purpose: Expose an HTTP interface to ingest or query Git repositories, chunk their contents, send to an AI summarizer, format results, and store/retrieve data.

##### File structure
- Top-level:
- `Dockerfile`, `docker-compose.yml`, `.github/workflows` ⇒ build, test, and deploy pipelines.
- `requirements.txt`, `pyproject.toml` ⇒ Python dependencies.
- `src/api`:
- `main.py` and `__main__.py`: app entrypoint.
- `routers`: endpoints for ingest, summary, health, index.
- `middleware`, `config`, `models`, `shared` ⇒ API-level components (request/response schemas, config injection, auth, error handling).
- `src/core`:
- `entrypoint.py`: CLI or worker entrypoint.
- `clone`, `chunking`, `parser`, `ai_summary`, `formatter`, `ingestion` modules ⇒ core domain services.
- `schemas` and `utils` ⇒ data definitions and helper functions.
- `src/storage`:
- `factory.py`, `base.py`, `local.py`, `gcs.py` ⇒ abstract factory for storage adapters.
- `templates` + `static`: server-rendered HTML pages and associated JavaScript.
- `tests`: unit tests for each core and storage component.

##### Elements
- Labels: “Browser”, “API Server”, “Core Logic”, “Storage Adapter”, “GCS / Local FS”, “AI Service”, “Git Remote”
– Green for core domain services
– Yellow for storage/persistence

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Presentation Layer)" 
        direction TB
        F_base["base.html"]:::frontend
        F_index["index.html"]:::frontend
        F_ingest["ingest.html"]:::frontend
        F_navbar["components/navbar.html"]:::frontend
        F_footer["components/footer.html"]:::frontend
        F_ingest_form["components/ingest_form.html"]:::frontend
        F_result["components/result.html"]:::frontend
        F_mainjs["static/js/main.js"]:::frontend
        F_ingestjs["static/js/ingest.js"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (FastAPI Server)" 
        direction TB
        API_main["main.py"]:::api
        API__main__["__main__.py"]:::api
        API_config["config.py"]:::api
        API_middleware["middleware.py"]:::api
        API_models["models.py"]:::api
        API_shared["shared.py"]:::api
        API_query["query_processor.py"]:::api
        API_index["routers/index.py"]:::api
        API_ingest["routers/ingest.py"]:::api
        API_summary["routers/summary.py"]:::api
        API_health["routers/health.py"]:::api
    end

    %% Core Business Logic
    subgraph "Core Business Logic" 
        direction TB
        CORE_entry["entrypoint.py"]:::core
        CORE_clone["clone.py"]:::core
        CORE_chunking["chunking.py"]:::core
        CORE_parser["parser.py"]:::core
        CORE_ai["ai_summary.py"]:::core
        CORE_formatter["formatter.py"]:::core
        CORE_output["output_formats.py"]:::core
        CORE_ingestion["ingestion.py"]:::core
        CORE_config["config.py"]:::core
        CORE_progress["progress.py"]:::core
        CORE_schemas["schemas/"]:::core
        CORE_utils["utils/"]:::core
    end

    %% Storage Layer
    subgraph "Storage Layer (Persistence)" 
        direction TB
        ST_factory["factory.py"]:::storage
        ST_base["base.py"]:::storage
        ST_local["local.py"]:::storage
        ST_gcs["gcs.py"]:::storage
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        EXT_git["Git Remote"]:::external
        EXT_ai["AI Service"]:::external
    end

    %% DevOps / CI-CD
    subgraph "DevOps / CI-CD" 
        direction TB
        DEV_dockerfile["Dockerfile"]:::devops
        DEV_compose["docker-compose.yml"]:::devops
        DEV_ci[".github/workflows/ci.yml"]:::devops
        DEV_deploy[".github/workflows/deploy.yml"]:::devops
    end

    %% Connections
    Browser["Browser/CLI"]:::client
    Browser -->|"HTTP Request"| API_main
    API_main -->|"calls routers"| API_index
    API_main -->|"calls routers"| API_ingest
    API_main -->|"calls routers"| API_summary
    API_main -->|"calls routers"| API_health
    API_index -->|"process request"| CORE_entry
    API_ingest -->|"process ingestion"| CORE_ingestion
    API_summary -->|"process summary"| CORE_ai
    CORE_entry --> CORE_clone
    CORE_clone -->|"git clone"| EXT_git
    CORE_clone -->|"stores files"| ST_local
    CORE_chunking --> CORE_parser
    CORE_parser --> CORE_ai
    CORE_ai -->|"calls AI API"| EXT_ai
    CORE_ai --> CORE_formatter
    CORE_formatter --> CORE_output
    CORE_ingestion --> ST_factory
    ST_factory --> ST_local
    ST_factory --> ST_gcs
    API_main -->|"renders HTML"| F_base
    F_base --> F_navbar
    F_base --> F_footer
    F_base --> F_index
    F_base --> F_ingest
    F_ingest --> F_ingest_form
    F_index --> F_result
    F_mainjs -->|"AJAX"| API_main
    F_ingestjs -->|"AJAX"| API_ingest
    DEV_ci --> DEV_dockerfile
    DEV_ci --> DEV_compose
    DEV_ci -->|"build/test"| DEV_compose
    DEV_deploy -->|"deploy images"| API_main

    %% Click Events Frontend
    click F_base "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/base.html"
    click F_index "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/index.html"
    click F_ingest "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/ingest.html"
    click F_navbar "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/components/navbar.html"
    click F_footer "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/components/footer.html"
    click F_ingest_form "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/components/ingest_form.html"
    click F_result "https://github.com/redfox1899/gitunderstand/blob/main/src/templates/components/result.html"
    click F_mainjs "https://github.com/redfox1899/gitunderstand/blob/main/static/js/main.js"
    click F_ingestjs "https://github.com/redfox1899/gitunderstand/blob/main/static/js/ingest.js"

    %% Click Events API
    click API_main "https://github.com/redfox1899/gitunderstand/blob/main/src/api/main.py"
    click API__main__ "https://github.com/redfox1899/gitunderstand/blob/main/src/api/__main__.py"
    click API_config "https://github.com/redfox1899/gitunderstand/blob/main/src/api/config.py"
    click API_middleware "https://github.com/redfox1899/gitunderstand/blob/main/src/api/middleware.py"
    click API_models "https://github.com/redfox1899/gitunderstand/blob/main/src/api/models.py"
    click API_shared "https://github.com/redfox1899/gitunderstand/blob/main/src/api/shared.py"
    click API_query "https://github.com/redfox1899/gitunderstand/blob/main/src/api/query_processor.py"
    click API_index "https://github.com/redfox1899/gitunderstand/blob/main/src/api/routers/index.py"
    click API_ingest "https://github.com/redfox1899/gitunderstand/blob/main/src/api/routers/ingest.py"
    click API_summary "https://github.com/redfox1899/gitunderstand/blob/main/src/api/routers/summary.py"
    click API_health "https://github.com/redfox1899/gitunderstand/blob/main/src/api/routers/health.py"

    %% Click Events Core
    click CORE_entry "https://github.com/redfox1899/gitunderstand/blob/main/src/core/entrypoint.py"
    click CORE_clone "https://github.com/redfox1899/gitunderstand/blob/main/src/core/clone.py"
    click CORE_chunking "https://github.com/redfox1899/gitunderstand/blob/main/src/core/chunking.py"
    click CORE_parser "https://github.com/redfox1899/gitunderstand/blob/main/src/core/parser.py"
    click CORE_ai "https://github.com/redfox1899/gitunderstand/blob/main/src/core/ai_summary.py"
    click CORE_formatter "https://github.com/redfox1899/gitunderstand/blob/main/src/core/formatter.py"
    click CORE_output "https://github.com/redfox1899/gitunderstand/blob/main/src/core/output_formats.py"
    click CORE_ingestion "https://github.com/redfox1899/gitunderstand/blob/main/src/core/ingestion.py"
    click CORE_config "https://github.com/redfox1899/gitunderstand/blob/main/src/core/config.py"
    click CORE_progress "https://github.com/redfox1899/gitunderstand/blob/main/src/core/progress.py"
    click CORE_schemas "https://github.com/redfox1899/gitunderstand/tree/main/src/core/schemas/"
    click CORE_utils "https://github.com/redfox1899/gitunderstand/tree/main/src/core/utils/"

    %% Click Events Storage
    click ST_factory "https://github.com/redfox1899/gitunderstand/blob/main/src/storage/factory.py"
    click ST_base "https://github.com/redfox1899/gitunderstand/blob/main/src/storage/base.py"
    click ST_local "https://github.com/redfox1899/gitunderstand/blob/main/src/storage/local.py"
    click ST_gcs "https://github.com/redfox1899/gitunderstand/blob/main/src/storage/gcs.py"

    %% Click Events DevOps
    click DEV_dockerfile "https://github.com/redfox1899/gitunderstand/tree/main/Dockerfile"
    click DEV_compose "https://github.com/redfox1899/gitunderstand/blob/main/docker-compose.yml"
    click DEV_ci "https://github.com/redfox1899/gitunderstand/blob/main/.github/workflows/ci.yml"
    click DEV_deploy "https://github.com/redfox1899/gitunderstand/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef api fill:#E8F1FF,stroke:#1A73E8,stroke-width:1px;
    classDef core fill:#E6FFEA,stroke:#34A853,stroke-width:1px;
    classDef storage fill:#FFF7E6,stroke:#FBBC05,stroke-width:1px;
    classDef external fill:#FFECEF,stroke:#EA4335,stroke-dasharray: 5 5,stroke-width:1px;
    classDef devops fill:#F1F3F4,stroke:#5F6368,stroke-width:1px;
    classDef client fill:#FFFFFF,stroke:#202124,stroke-width:1px;
```
