How vicevilz/docugen-ai works
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.