# enesmanan/gitarch architecture

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

- Interactive diagram: https://gitdiagram.com/enesmanan/gitarch
- Repository: https://github.com/enesmanan/gitarch

## Overview

##### What this project is (inferred from tree + minimal README)
**GitArch** appears to be a **Python application that analyzes a Git repository and produces an “architecture/report” artifact**, likely by:
- **Cloning/loading a repo** (via `repo_manager.py`)
- **Building a structured context** from the repo (`context_builder.py`, `tools.py`)
- **Running a multi-step “agent” pipeline** (`agents/*`, orchestrated by `agents/orchestrator.py`)
- **Calling an external LLM provider (Gemini)** (`gemini_client.py`)
- **Presenting results via a web UI** (presence of `templates/index.html`, `templates/report.html`, `static/svg` strongly suggests server-rendered HTML)

##### Request-driven UI flow (user triggers analysis from a web page)
2) **Analysis pipeline** (repo ingestion → context building → agent execution → report generation)

##### Orchestrator calls Repo Manager to fetch/open the repository.
5. **Repo Manager** reads/writes from **Local Filesystem** (and optionally hits **Remote Git host** if cloning).

##### Context Builder creates structured context from repo contents.
7. **Orchestrator** calls each **Agent** module (structure → overview → architecture → features → quality → summary).

##### Gemini Client calls Gemini API and returns responses.
10. Agents produce intermediate artifacts that feed into subsequent agents and ultimately into the final report.

##### Output → Templates → Report page
11. The final synthesized report is rendered via **`templates/report.html`** and served back to the browser.

##### Architectural patterns worth highlighting (specific to this structure)
- **Pipeline / staged processing**: multiple sequential analysis stages, each producing artifacts for the next.
- **Strategy/Plugin-like “Agent” pattern**: `agents/base.py` suggests a common interface; each agent is a replaceable module.
- **Orchestrator pattern**: central coordinator controlling flow and dependencies.
- **Adapter pattern** for external AI: `gemini_client.py` isolates API details from business logic.

##### Don’t overthink: capture “as many components as possible,” but keep truthfulness
Because the README is empty, avoid inventing specifics like “Redis cache” or “PostgreSQL” unless you confirm via `requirements.txt` or code.
But it *is* accurate and useful to:
- A generic “Web Framework runtime”
- “Local filesystem workspace”
- “External LLM API (Gemini)”
- Break agents into individual components (they exist in the tree)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1 — System Context
  %% =========================
  subgraph "Level 1 — System Context"
    U["User (Browser)"]:::external

    subgraph "GitArch System"
      APP["Python Web App (Entry Point)"]:::app
      CORE["Analysis Pipeline (GitArch)"]:::core
    end

    GIT["Remote Git Provider (Optional)"]:::external
    GEM["Gemini LLM Service (API)"]:::external
    FS[(Local Repo Workspace\nFilesystem)]:::storage
  end

  U -->|"Analyze_repo_request (repo_url/path,options)"| APP
  APP -->|"Triggers_analysis_run"| CORE
  CORE -->|"LLM_requests (prompts)"| GEM
  CORE -->|"Repo_clone/fetch (optional)"| GIT
  CORE -->|"Read/write_repo_workspace"| FS
  APP -->|"Rendered_HTML_report"| U

  %% ==================================
  %% Level 2 — Containers / Major Pieces
  %% ==================================
  subgraph "Level 2 — Containers"
    direction TB

    subgraph "Presentation Layer"
      direction TB
      TIDX["Template: Index Page"]:::ui
      TRPT["Template: Report Page"]:::ui
      SVG["Static Assets (SVG)"]:::ui
    end

    subgraph "Application Host"
      direction TB
      MAIN["main.py (Web Framework Runtime)"]:::app
    end

    subgraph "Core Orchestration"
      direction TB
      ORCH["Orchestrator"]:::core
      NOTE1["Pattern: Orchestrator + Pipeline (staged_processing)"]:::note
    end

    subgraph "Analysis Components"
      direction TB
      CTX["Context Builder"]:::core
      TOOLS["Shared Tools/Utilities"]:::core
      NOTE2["Pattern: Agent Strategy/Plugin (common_interface)"]:::note
    end

    subgraph "Agents (Pipeline Stages)"
      direction TB
      BASE["Agent Base / Contract"]:::agent
      A1["Structure Agent"]:::agent
      A2["Code Overview Agent"]:::agent
      A3["Architecture Agent"]:::agent
      A4["Features Agent"]:::agent
      A5["Quality/Risks Agent"]:::agent
      A6["Summary Agent"]:::agent
    end

    subgraph "Integrations / IO"
      direction TB
      REPO["Repo Manager"]:::integration
      GEMCLI["Gemini Client"]:::integration
      NOTE3["Pattern: Adapter (isolates LLM API details)"]:::note
    end

    subgraph "Runtime/Dependencies (Notes)"
      direction TB
      REQ["requirements.txt"]:::note
      PYV[".python-version"]:::note
    end
  end

  %% Container connections
  MAIN -->|"Serves_HTML (SSR) + static_files"| TIDX
  MAIN -->|"Serves_report_view"| TRPT
  MAIN -->|"Serves_static_assets"| SVG

  TIDX -->|"Form_submit/analyze_request"| MAIN
  MAIN -->|"Start_pipeline (repo_url/path,options)"| ORCH

  ORCH -->|"Checkout/open_repo"| REPO
  REPO -->|"Read/write_worktree"| FS
  REPO -->|"Clone/fetch (optional)"| GIT

  ORCH -->|"Build_context (file_list,metadata,content)"| CTX
  CTX -->|"Uses_utilities (filtering,reading,chunking)"| TOOLS

  ORCH -->|"Execute_stage_1"| A1
  ORCH -->|"Execute_stage_2"| A2
  ORCH -->|"Execute_stage_3"| A3
  ORCH -->|"Execute_stage_4"| A4
  ORCH -->|"Execute_stage_5"| A5
  ORCH -->|"Execute_stage_6"| A6

  BASE -->|"Defines_interface"| A1
  BASE -->|"Defines_interface"| A2
  BASE -->|"Defines_interface"| A3
  BASE -->|"Defines_interface"| A4
  BASE -->|"Defines_interface"| A5
  BASE -->|"Defines_interface"| A6

  A1 -->|"Prompt (context+task)"| GEMCLI
  A2 -->|"Prompt (context+task)"| GEMCLI
  A3 -->|"Prompt (context+task)"| GEMCLI
  A4 -->|"Prompt (context+task)"| GEMCLI
  A5 -->|"Prompt (context+task)"| GEMCLI
  A6 -->|"Prompt (context+task)"| GEMCLI

  GEMCLI -->|"LLM_request"| GEM
  GEM -->|"LLM_response"| GEMCLI

  A1 -->|"Intermediate_findings"| ORCH
  A2 -->|"Intermediate_findings"| ORCH
  A3 -->|"Intermediate_findings"| ORCH
  A4 -->|"Intermediate_findings"| ORCH
  A5 -->|"Intermediate_findings"| ORCH
  A6 -->|"Final_synthesis"| ORCH

  ORCH -->|"Final_report_model"| MAIN
  MAIN -->|"Render (report_model)"| TRPT
  TRPT -->|"HTML_report"| U

  NOTE1 -.-> ORCH
  NOTE2 -.-> BASE
  NOTE3 -.-> GEMCLI
  REQ -.-> MAIN
  PYV -.-> MAIN

  %% ==================================
  %% Level 3 — Component Zoom-in (Core)
  %% ==================================
  subgraph "Level 3 — Component Zoom-in (Pipeline Internals)"
    direction TB

    ZORCH["Orchestrator (sequencing + artifact aggregation)"]:::core
    ZCTX["Context Builder (LLM-ready context)"]:::core
    ZTOOLS["tools.py (shared helpers)"]:::core

    subgraph "Ordered Agent Stages"
      direction TB
      Z1["1) Structure"]:::agent
      Z2["2) Code Overview"]:::agent
      Z3["3) Architecture"]:::agent
      Z4["4) Features"]:::agent
      Z5["5) Quality/Risks"]:::agent
      Z6["6) Summary"]:::agent
    end

    ZGEM["Gemini Client (LLM adapter)"]:::integration
  end

  ZORCH -->|"Build_context"| ZCTX
  ZCTX -->|"Uses"| ZTOOLS

  ZORCH -->|"Run"| Z1 -->|"Findings_to_next"| Z2 -->|"Findings_to_next"| Z3 -->|"Findings_to_next"| Z4 -->|"Findings_to_next"| Z5 -->|"Findings_to_next"| Z6
  Z1 -->|"Prompt"| ZGEM
  Z2 -->|"Prompt"| ZGEM
  Z3 -->|"Prompt"| ZGEM
  Z4 -->|"Prompt"| ZGEM
  Z5 -->|"Prompt"| ZGEM
  Z6 -->|"Prompt"| ZGEM
  ZGEM -->|"Calls"| GEM

  %% =========================
  %% Click Events (Mapped Paths)
  %% =========================
  click MAIN "https://github.com/enesmanan/gitarch/blob/main/main.py"
  click TIDX "https://github.com/enesmanan/gitarch/blob/main/templates/index.html"
  click TRPT "https://github.com/enesmanan/gitarch/blob/main/templates/report.html"
  click SVG "https://github.com/enesmanan/gitarch/tree/main/static/svg/"
  click ORCH "https://github.com/enesmanan/gitarch/blob/main/agents/orchestrator.py"
  click BASE "https://github.com/enesmanan/gitarch/blob/main/agents/base.py"
  click A1 "https://github.com/enesmanan/gitarch/blob/main/agents/structure.py"
  click A2 "https://github.com/enesmanan/gitarch/blob/main/agents/code_overview.py"
  click A3 "https://github.com/enesmanan/gitarch/blob/main/agents/architecture.py"
  click A4 "https://github.com/enesmanan/gitarch/blob/main/agents/features.py"
  click A5 "https://github.com/enesmanan/gitarch/blob/main/agents/quality.py"
  click A6 "https://github.com/enesmanan/gitarch/blob/main/agents/summary.py"
  click CORE "https://github.com/enesmanan/gitarch/blob/main/agents/__init__.py"
  click REPO "https://github.com/enesmanan/gitarch/blob/main/repo_manager.py"
  click CTX "https://github.com/enesmanan/gitarch/blob/main/context_builder.py"
  click TOOLS "https://github.com/enesmanan/gitarch/blob/main/tools.py"
  click GEMCLI "https://github.com/enesmanan/gitarch/blob/main/gemini_client.py"
  click REQ "https://github.com/enesmanan/gitarch/blob/main/requirements.txt"
  click PYV "https://github.com/enesmanan/gitarch/blob/main/.python-version"

  %% =========================
  %% Styles
  %% =========================
  classDef app fill:#2563eb,stroke:#1e3a8a,stroke-width:2px,color:#ffffff
  classDef ui fill:#14b8a6,stroke:#0f766e,stroke-width:2px,color:#072b2a
  classDef core fill:#7c3aed,stroke:#4c1d95,stroke-width:2px,color:#ffffff
  classDef agent fill:#a855f7,stroke:#581c87,stroke-width:2px,color:#ffffff
  classDef integration fill:#f59e0b,stroke:#92400e,stroke-width:2px,color:#2b1600
  classDef storage fill:#94a3b8,stroke:#334155,stroke-width:2px,color:#0b1220
  classDef external fill:#0f172a,stroke:#334155,stroke-width:2px,color:#e2e8f0
  classDef note fill:#fef3c7,stroke:#d97706,stroke-width:1px,color:#3b2500,stroke-dasharray:4 3
```
