# egouilliard/codex-arch architecture

> Architecture diagram of the GitHub repository egouilliard/codex-arch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/egouilliard/codex-arch
- Repository: https://github.com/egouilliard/codex-arch

## Overview

##### Project Type and Purpose
- Codex‑Arch is a Python‑based, command‑line and REST‑API tool for analyzing, visualizing, and summarizing code architecture.
- It ingests a codebase (via CLI or API), runs extractors (dependency/file‑tree), analyzers (metrics, change detection), builds summaries, bundles results, and emits visualizations (GraphViz).

##### High‑Level File‑Structure Analysis
- Interfaces:
- codex_arch/cli – Click‑based commands (analyze, dependencies, filetree, run‑all, etc.)
- codex_arch/api – HTTP REST service (app.py, auth, routes, cache, docs).
- Core Engine:
- codex_arch/analyzer.py – orchestration of analysis tasks
- codex_arch/extractors – source‐language parsers and exporters
- codex_arch/metrics – complexity and language metrics
- codex_arch/change_detection – git‑change detection and caching
- codex_arch/summary – smart summarization pipeline
- codex_arch/bundler – context assembly of heterogeneous outputs
- Visualization:
- codex_arch/visualization – GraphViz dot generation and converters
- generate_arch_graph.py, convert_deps.py – standalone scripts
- Infrastructure:
- codex_arch/storage.py – result persistence
- codex_arch/api/cache – in‑memory or file cache for API
- codex_arch/hooks – git‑hook integration and notifications
- Supporting files: tests/, docs/, config (pytest.ini, pyproject.toml), CI workflows, packaging scripts.

##### Main Architectural Components
- Presentation Layer:
- CLI interface (Click commands)
- REST API (Flask/FastAPI‑style app with token auth + Swagger docs)
- Application/Orchestration Layer:
- Analyzer coordinator (orchestrates extractors, metrics, change_detection, summary, bundler)
- Hooks manager (invoked via git hooks or CLI)
- Domain Logic Layer:
- Extractors: parse code, build dependency and file‑tree models
- Metrics analyzers: compute complexity, language statistics
- Change detector: analyze git diffs, incremental changes
- Summarizer: assemble human‑readable summaries
- Visualization Layer:
- Dot generator and graph converter producing SVG/PNG via GraphViz
- Data Layer:
- Storage: file system persistence (JSON, Markdown)
- API cache: temporary in‑memory/file cache
- External Systems:
- Git repositories (for change detection)
- GraphViz (for rendering)
- Client shells or HTTP clients

##### Relationships and Data Flows
- CLI/API → Analyzer coordinator: receives user request (e.g., “analyze”), passes parameters.
- Analyzer → Extractors → produces raw data (dependency JSON, file tree JSON).
- Analyzer → Metrics/Change_Detection/Summary modules → produce enriched artifacts.
- Bundler collects all outputs into a “context bundle.”
- Visualization module (or separate script) consumes dependency JSON or bundle, emits GraphViz DOT → renders images.
- Storage persists intermediate/final artifacts to disk or cache.
- Hooks module can trigger CLI or API calls on git events.

##### Architectural Patterns and Design Principles
- Layered architecture separating Interface / Orchestration / Domain logic / Persistence.
- Modular design (extractors, metrics, summary, visualization each independently testable).
- Single‑Responsibility: each module handles one analysis concern.
- Dependency Injection via configuration (codex_arch/api/config.py).
- Pluggable I/O: CLI, API, scripts all reuse the same core engine.
- Caching layer in API to improve performance for repeat queries.

##### Technologies and Frameworks
- Python 3.7+
- Click (CLI)
- Flask or FastAPI‐style HTTP service
- GraphViz (dot) for visualization
- Git (via command line or GitPython abstraction)
- Pytest for testing
- JSON/Markdown for artifact serialization

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        CLI(("CLI Interface")):::interface
        API(("REST API Interface")):::interface
    end

    subgraph "Application Layer"
        Analyzer["Analyzer Coordinator"]:::core
        Hooks["Hooks Manager"]:::core
    end

    subgraph "Domain Logic Layer"
        FileTree["File-Tree Extractor"]:::core
        PythonExt["Python Extractor Suite"]:::core
        Metrics["Metrics Analyzer"]:::core
        ChangeDetect["Change Detector"]:::core
        Summarizer["Summarizer"]:::core
        Bundler["Context Bundle Assembler"]:::core
    end

    subgraph "Visualization Layer"
        DotGen["GraphViz DOT Generator"]:::core
        Converter["Visualization Converter"]:::core
        GraphGen["Graph Generator"]:::core
        Script1(["generate_arch_graph.py"]):::external
        Script2(["convert_deps.py"]):::external
    end

    subgraph "Data Layer"
        Storage[("Storage")]:::data
        APICache[("API Cache")]:::data
    end

    subgraph "External Systems"
        GitRepo(("Git Repository")):::external
        GraphViz(("GraphViz")):::external
        ClientShell(("Client Shell")):::external
        HTTPClient(("HTTP Client")):::external
    end

    ClientShell -->|"CLI call"| CLI
    HTTPClient -->|"HTTP request"| API
    CLI -->|"analyze() request"| Analyzer
    API -->|"analyze() request"| Analyzer
    Analyzer -->|"invoke extractor"| FileTree
    FileTree -->|"dependency-json"| Analyzer
    Analyzer -->|"invoke extractor"| PythonExt
    PythonExt -->|"dependency-json"| Analyzer
    Analyzer -->|"invoke metrics"| Metrics
    Metrics -->|"metrics.json"| Analyzer
    Analyzer -->|"invoke change detection"| ChangeDetect
    ChangeDetect -->|"changes.json"| Analyzer
    Analyzer -->|"invoke summarizer"| Summarizer
    Summarizer -->|"summary.txt"| Analyzer
    Analyzer -->|"assemble bundle"| Bundler
    Bundler -->|"context bundle"| Analyzer
    Analyzer -->|"persist artifacts"| Storage
    Bundler -->|"persist bundle"| Storage
    API -->|"cache lookup/store"| APICache
    APICache -->|"cached data"| Analyzer
    GitRepo -->|"git event"| Hooks
    Hooks -->|"trigger CLI"| CLI
    Hooks -->|"trigger API"| API
    Analyzer -->|"bundle input"| DotGen
    Bundler -->|"bundle input"| DotGen
    DotGen -->|"dot output"| Converter
    Converter -->|"svg/png"| GraphViz
    Script1 -->|"uses dot generator"| DotGen
    Script2 -->|"uses converter"| DotGen

    click CLI "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/cli/"
    click API "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/api/"
    click Analyzer "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/analyzer.py"
    click FileTree "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/extractors/file_tree_extractor.py"
    click PythonExt "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/extractors/python/"
    click Metrics "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/metrics/"
    click ChangeDetect "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/change_detection/"
    click Summarizer "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/summary/"
    click Bundler "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/bundler/context_bundle_assembler.py"
    click DotGen "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/visualization/graph/dot_generator.py"
    click Converter "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/visualization/converter.py"
    click GraphGen "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/visualization/graph_generator.py"
    click Script1 "https://github.com/egouilliard/codex-arch/blob/main/generate_arch_graph.py"
    click Script2 "https://github.com/egouilliard/codex-arch/blob/main/convert_deps.py"
    click Storage "https://github.com/egouilliard/codex-arch/blob/main/codex_arch/storage.py"
    click APICache "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/api/cache/"
    click Hooks "https://github.com/egouilliard/codex-arch/tree/main/codex_arch/hooks/"

    classDef interface fill:#FFD966,stroke:#333,stroke-width:1px
    classDef core fill:#8DB4E2,stroke:#333,stroke-width:1px
    classDef data fill:#B6D7A8,stroke:#333,stroke-width:1px
    classDef external fill:#F4CCCC,stroke:#333,stroke-width:1px
```
