How egouilliard/codex-arch works
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