# vicevilz/docugen-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vicevilz/docugen-ai
- Repository: https://github.com/vicevilz/docugen-ai

## Overview

##### Tipo y propósito del proyecto (qué estás diagramando)
**DocuGen** es una **herramienta CLI en Python** (no es un servicio web) para **generar documentación técnica (README/Markdown)** a partir de **análisis estático del código Python (AST)** y la **síntesis con un LLM vía Google Gemini**.
Arquitectónicamente es un **pipeline por fases** que toma como input un directorio de proyecto y produce como output un archivo Markdown renderizado con plantillas.

Para el diagrama, tu “sistema” no es una app desplegada con runtime distribuido, sino un **ejecutable local** (CLI) que orquesta módulos internos y una dependencia externa (Gemini API).

##### Lectura del file tree (cómo está organizado)
Componentes principales inferidos por carpetas:

- `docugen/cli.py`
Entrada principal; define comandos (Typer según README) y argumentos.
- `docugen/core/`
Pipeline “core” de análisis estático:
- `scanner.py`: selección de archivos (respeta `.gitignore`)
- `parser.py`: AST parsing / extracción de clases/funciones
- `processor.py`: normalización / preparación de metadatos para el LLM
- `docugen/api/gemini_client.py`
Integración externa: construcción de cliente, request/response y salida Markdown.
- `docugen/templates/`
Rendering:
- `engine.py`: motor de plantillas (Jinja2 por README/roadmap)
- `default_readme.md.j2`: template por defecto
- `docugen/utils/`
Infra:
- `config_manager.py`: config desde CLI + TOML/dotenv (README)
- `logger.py`: logging
- `tests/`
Suite pytest separada por módulo (buena señal para diagramar boundaries claros).
- `pyproject.toml`, `uv.lock`, `docugen_ai.egg-info/`
Empaquetado/distribución, entrypoints (CLI), dependencias.

Esto sugiere una **arquitectura modular y desacoplada**: CLI → core pipeline → AI client → template engine.

##### Señales adicionales del README (qué enfatizar)
El README ya define explícitamente una **arquitectura de 3 fases**:

##### Synthesis & Rendering (`api/gemini_client.py`, `templates/engine.py`)

Tu diagrama debe reflejar exactamente esas fases, y además mostrar los “cross-cutting concerns”:
- Configuración (TOML/dotenv/CLI)
- `.gitignore` como input al scanner
- Logging
- Red externa: Google Gemini API
- Output file(s): `README.md` u otro especificado con `--output`

##### El “System Context” (C4 nivel 1)
Dibuja una caja “DocuGen (CLI Tool)” y alrededor:
- **Usuario/Developer** (actor) ejecuta comandos `docugen generate ...`
- **File System / Target Python Project** (carpeta) como fuente de código
- **Google Gemini API** como sistema externo (red)
- **Output Markdown** escrito al filesystem

**Flechas principales:**
- Usuario → DocuGen: comandos/flags/prompt
- DocuGen → File System: lectura de `.py`, `.gitignore`, config
- DocuGen → Gemini API: request con contexto normalizado
- DocuGen → File System: escritura `README.md`/`DOCUMENTATION.md`

##### Diagrama de “Container/Component” (C4 nivel 2/3) ajustado a este repo
Dentro de “DocuGen”, separa en componentes (idealmente por paquetes del repo):

##### CLI Layer
- `docugen/cli.py`
Responsabilidad: parsear args, resolver paths, invocar pipeline, manejar errores/salida.

##### Config & Observability (cross-cutting)
- `utils/config_manager.py` (entrada: CLI args + TOML/dotenv + env vars)
- `utils/logger.py`
Estos módulos “tocan” todas las fases; dibújalos como cajas laterales conectadas por líneas punteadas (dependency).

##### Core Pipeline (dibújalo en 3 sub-bloques secuenciales)
- **Scanner**: `core/scanner.py`
Inputs: root dir, `.gitignore`, reglas de inclusión
Output: lista de archivos Python/targets
- **Parser**: `core/parser.py`
Input: paths/contents
Output: AST-derived metadata (clases, funciones, firmas)
- **Processor**: `core/processor.py`
Input: metadata “raw”
Output: “normalized context” (plano/limpio para LLM)

##### AI Integration
- `api/gemini_client.py`
Inputs: normalized context, model name, prompt
Output: texto Markdown (o secciones) generado por LLM
External dependency: **Gemini SDK / HTTP** (muéstralo como “Gemini API” fuera del boundary)

##### Template & Rendering
- `templates/engine.py` (Jinja2 engine)
- `templates/default_readme.md.j2` (artefacto template)
Inputs: texto generado + metadata extra
Output: Markdown final consistente con estándar README

##### Tests (opcional en diagrama principal)
- `tests/test_*.py`
Si haces un diagrama “dev view”, muestra tests apuntando a cada componente.

##### Relaciones/Interacciones (qué flechas no pueden faltar)
Dibuja el flujo “happy path” como pipeline:

`CLI` → `ConfigManager` (resolver config)
`CLI` → `Scanner` → `Parser` → `Processor` → `GeminiClient` → `TemplateEngine` → `Write Output`

Y dependencias laterales:
- `Scanner` → `.gitignore` (lectura)
- `GeminiClient` → `Gemini API` (red)
- `All modules` → `Logger` (punteado)
- `TemplateEngine` → `default_readme.md.j2` (artefacto)

Incluye también el **artefacto clave**: “Normalized Metadata/Context” como un nodo intermedio (document/data object), porque es el contrato entre Core y AI.

- **Pipeline / staged architecture**: etapas con outputs bien definidos (file list → metadata → normalized context → generated text → rendered doc).
- **Separation of concerns**:
- Core (determinístico) vs AI (no determinístico) vs Presentation (templates).
- **Extensibilidad**:
- Nuevos renderers/templates (Wiki/HTML/PDF) → `templates/engine.py`
- Nuevos lenguajes (roadmap) → extender `scanner` y probablemente `parser`
- **Boundary explícito con externos**:
- Gemini API como “system external”, con un único adaptador `GeminiClient`.

##### Guías específicas para este tipo de proyecto (CLI tool + LLM)
Como no hay “frontend/backend/database”, tu diagrama debe centrarse en:
- **Entradas**: directorio objetivo, prompt, configuración, `.gitignore`
- **Transformaciones**: AST → metadata → normalization → prompt/context packing
- **Llamada externa**: Gemini API (latencia, credenciales)
- **Salida**: Markdown (y template aplicado)

Si quieres máxima precisión, agrega:
- Un bloque “Credential Source” (ENV/DOTENV/TOML) que alimenta a `GeminiClient._build_client`.
- Un bloque “Packaging/Entrypoint” (pyproject/entry_points) que explica cómo `docugen` se expone como comando.

##### Convenciones visuales (lo que debe aparecer sí o sí)
Para que el diagrama sea “engineering-grade”:

##### Elementos
- **Cajas** por módulo/paquete (nombres exactos: `docugen/core/scanner.py`, etc.)
- Flechas sólidas: flujo de datos (pipeline)
- Flechas punteadas: dependencias (logger/config)
- **Data artifacts** (documentos):
- “File list”
- “AST metadata”
- “Normalized context”
- “Generated markdown draft”
- “Final README.md”

##### Processor → *Normalized context*

Luego:
##### GeminiClient → (external) Gemini API → *Generated markdown*

Luego:
##### TemplateEngine + default_readme.md.j2 → *Final README.md* (filesystem)

Ese diagrama, con labels exactos y artefactos de datos intermedios, será el más fiel a la estructura real del repo.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% System Context (C4 L1)
%% =========================
U["Developer/User"]:::actor
FS["Local File System\n(Target Python Project)"]:::fs
GAPI["Google Gemini API\n(External LLM Service)"]:::external
OUT["Markdown Output File(s)\nREADME.md / DOCUMENTATION.md"]:::fs

%% =========================
%% DocuGen Boundary (CLI tool)
%% =========================
subgraph "DocuGen (Python CLI Tool)"
direction TB

    %% -------- CLI Layer --------
    subgraph "CLI Layer"
    direction TB
        CLI["CLI Entrypoint\n(docugen/cli.py)"]:::cli
        PKG["Packaging & CLI Exposure\n(pyproject.toml)"]:::pkg
        EP["Installed Entrypoint Metadata\n(entry_points.txt)"]:::pkg
    end

    %% -------- Cross-cutting --------
    subgraph "Config & Observability (Cross-cutting)"
    direction TB
        CFG["Config Manager\n(utils/config_manager.py)"]:::config
        LOG["Logger\n(utils/logger.py)"]:::config
    end

    %% -------- Core Pipeline (3 phases) --------
    subgraph "Core Pipeline (Deterministic)"
    direction TB

        subgraph "Phase 1: Ingestion & Scanning"
        direction TB
            SCN["Scanner\n(core/scanner.py)"]:::core
            GIT[".gitignore (input rules)"]:::fs
            D1[("File list\n(.py targets)")]:::data
        end

        subgraph "Phase 2: Parsing & Normalization"
        direction TB
            PAR["Parser\n(core/parser.py)"]:::core
            D2[("AST metadata\n(classes/functions/signatures)")]:::data
            PRO["Processor\n(core/processor.py)"]:::core
            D3[("Normalized context\n(LLM-ready)")]:::data
        end
    end

    %% -------- AI Integration --------
    subgraph "AI Integration (Non-deterministic)"
    direction TB
        GEM["Gemini Client Adapter\n(api/gemini_client.py)"]:::ai
        D4[("Generated markdown draft\n(LLM output)")]:::data
    end

    %% -------- Templates & Rendering --------
    subgraph "Synthesis & Rendering"
    direction TB
        ENG["Template Engine (Jinja2)\n(templates/engine.py)"]:::render
        TPL["Default Template\n(default_readme.md.j2)"]:::artifact
        D5[("Final rendered Markdown\n(README content)")]:::data
    end

end

%% =========================
%% Primary flow (solid arrows)
%% =========================
U -->|"runs docugen generate + flags"| CLI
CLI -->|"reads/writes project files"| FS

CLI -->|"load config"| CFG
CLI -->|"orchestrates"| SCN

FS -->|"project root directory"| SCN
GIT -->|"ignore rules"| SCN
SCN -->|"outputs"| D1
D1 -->|"inputs"| PAR
PAR -->|"extracts"| D2
D2 -->|"inputs"| PRO
PRO -->|"normalizes"| D3

D3 -->|"prompt/context"| GEM
GEM -->|"HTTP/SDK request"| GAPI
GAPI -->|"LLM response"| GEM
GEM -->|"outputs"| D4

D4 -->|"render inputs"| ENG
TPL -->|"template artifact"| ENG
ENG -->|"renders"| D5
D5 -->|"write"| OUT
CLI -->|"writes output file"| OUT

%% =========================
%% Cross-cutting dependencies (dotted)
%% =========================
CFG -.->|"config values"| SCN
CFG -.->|"config values"| PAR
CFG -.->|"config values"| PRO
CFG -.->|"model/prompt/credentials"| GEM
CFG -.->|"render settings"| ENG

LOG -.->|"logs"| CLI
LOG -.->|"logs"| SCN
LOG -.->|"logs"| PAR
LOG -.->|"logs"| PRO
LOG -.->|"logs"| GEM
LOG -.->|"logs"| ENG

PKG -->|"defines entrypoint 'docugen'"| CLI
EP -->|"installed console_scripts"| CLI

%% =========================
%% Tests (optional dev view)
%% =========================
subgraph "Test Suite (pytest)"
direction TB
    TCONF["tests/conftest.py"]:::test
    TCLI["tests/test_cli.py"]:::test
    TSCN["tests/test_scanner.py"]:::test
    TPAR["tests/test_parser.py"]:::test
    TPRO["tests/test_processor.py"]:::test
    TGEM["tests/test_gemini_client.py"]:::test
    TENG["tests/test_engine.py"]:::test
end

TCONF -.->|"fixtures"| TCLI
TCONF -.->|"fixtures"| TSCN
TCONF -.->|"fixtures"| TPAR
TCONF -.->|"fixtures"| TPRO
TCONF -.->|"fixtures"| TGEM
TCONF -.->|"fixtures"| TENG

TCLI -.->|"tests"| CLI
TSCN -.->|"tests"| SCN
TPAR -.->|"tests"| PAR
TPRO -.->|"tests"| PRO
TGEM -.->|"tests"| GEM
TENG -.->|"tests"| ENG

%% =========================
%% Click events (from mapping)
%% =========================
click CLI "https://github.com/vicevilz/docugen-ai/blob/main/docugen/cli.py"
click SCN "https://github.com/vicevilz/docugen-ai/blob/main/docugen/core/scanner.py"
click PAR "https://github.com/vicevilz/docugen-ai/blob/main/docugen/core/parser.py"
click PRO "https://github.com/vicevilz/docugen-ai/blob/main/docugen/core/processor.py"
click GEM "https://github.com/vicevilz/docugen-ai/blob/main/docugen/api/gemini_client.py"
click ENG "https://github.com/vicevilz/docugen-ai/blob/main/docugen/templates/engine.py"
click TPL "https://github.com/vicevilz/docugen-ai/blob/main/docugen/templates/default_readme.md.j2"
click CFG "https://github.com/vicevilz/docugen-ai/blob/main/docugen/utils/config_manager.py"
click LOG "https://github.com/vicevilz/docugen-ai/blob/main/docugen/utils/logger.py"
click PKG "https://github.com/vicevilz/docugen-ai/blob/main/pyproject.toml"
click EP "https://github.com/vicevilz/docugen-ai/blob/main/docugen_ai.egg-info/entry_points.txt"
click TCLI "https://github.com/vicevilz/docugen-ai/blob/main/tests/test_cli.py"
click TSCN "https://github.com/vicevilz/docugen-ai/blob/main/tests/test_scanner.py"
click TPAR "https://github.com/vicevilz/docugen-ai/blob/main/tests/test_parser.py"
click TPRO "https://github.com/vicevilz/docugen-ai/blob/main/tests/test_processor.py"
click TGEM "https://github.com/vicevilz/docugen-ai/blob/main/tests/test_gemini_client.py"
click TENG "https://github.com/vicevilz/docugen-ai/blob/main/tests/test_engine.py"
click TCONF "https://github.com/vicevilz/docugen-ai/blob/main/tests/conftest.py"
click GIT "https://github.com/vicevilz/docugen-ai/blob/main/.gitignore"

%% =========================
%% Styles (color-coded)
%% =========================
classDef actor fill:#f4f7ff,stroke:#2b4dbb,stroke-width:2px,color:#0f1f4d
classDef cli fill:#e6f0ff,stroke:#1d4ed8,stroke-width:2px,color:#0b1b3a
classDef core fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#0b1b3a
classDef ai fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#3b2207
classDef render fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#06250f
classDef artifact fill:#ecfccb,stroke:#65a30d,stroke-width:2px,color:#1f2a07
classDef config fill:#d1fae5,stroke:#059669,stroke-width:2px,color:#062a1e
classDef fs fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#111827
classDef external fill:#ffe4e6,stroke:#e11d48,stroke-width:2px,color:#3a0712
classDef data fill:#fff7ed,stroke:#c2410c,stroke-width:2px,color:#3b1305
classDef pkg fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#1f1140
classDef test fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px,color:#22114a
```
