Trazo
Documentación de arquitectura que no se queda obsoleta.
Trazo extrae la estructura de tu sistema a partir del código y de los archivos de infraestructura, genera diagramas Mermaid y avisa de los cambios de arquitectura en cada pull request.
Es un proyecto personal y de código abierto: no se construyó para ninguna empresa ni con ninguna.
- Tipo
- Proyecto propio · sin empresa
- Rol
- Autor y mantenedor
- Enfoque
- Herramientas para desarrolladores · Arquitectura como código · CI
Los diagramas se pudren
Alguien dibuja un diagrama de arquitectura, el sistema cambia, y unas semanas después el diagrama es incorrecto y nadie confía en él.
Trazo adopta otro enfoque: el diagrama nunca se dibuja a mano ni se adivina.
Generado a partir de los archivos que ya definen tu sistema
La estructura sale de analizar los archivos que ya describen el sistema, y se vuelve a comprobar en cada pull request, de modo que un cambio de arquitectura aparece en la revisión en lugar de descubrirse meses después.
- Determinista. La estructura sale de analizar archivos, no de un modelo de lenguaje, así que el diagrama no puede inventar cosas que no existen.
- Vive en la PR. Quien revisa ve qué componentes y dependencias añade o elimina un cambio, junto al código.
- Sin servidor ni cuenta. Lee los archivos de tu repositorio y se ejecuta en local, en cualquier CI o como una GitHub Action que no necesita más que un archivo de workflow.
Un ejemplo
Dado un archivo Docker Compose con seis servicios, Trazo genera el diagrama de abajo.
Las bases de datos, cachés y colas se reconocen por su imagen y se dibujan con su propia forma y color de borde: servicios en azul, bases de datos en naranja, cachés en verde azulado, colas en amarillo. Un componente añadido por una pull request se marca en verde.
%%{init: {'theme':'base','themeVariables':{'lineColor':'#6b7280'}}}%%
flowchart LR
n_api["api"]
n_cache(["cache"])
n_db[("db")]
n_queue>"queue"]
n_web["web"]
n_worker["worker"]
n_api --> n_cache
n_api --> n_db
n_api --> n_queue
n_web --> n_api
n_worker --> n_db
n_worker --> n_queue
classDef kind_service fill:#e5effa,stroke:#2a78d6,stroke-width:2px,color:#1a1a1a
class n_api,n_web,n_worker kind_service
classDef kind_database fill:#fdede7,stroke:#eb6834,stroke-width:2px,color:#1a1a1a
class n_db kind_database
classDef kind_cache fill:#e4f5ef,stroke:#1baf7a,stroke-width:2px,color:#1a1a1a
class n_cache kind_cache
classDef kind_queue fill:#fdf4e0,stroke:#eda100,stroke-width:2px,color:#1a1a1a
class n_queue kind_queueQué lee
Hoy Trazo lee archivos Docker Compose (services, depends_on y links) y manifiestos de Kubernetes.
En Kubernetes, cada Deployment, StatefulSet, DaemonSet, Job, CronJob y Pod se convierte en un componente, y un Ingress se enlaza con la carga de trabajo que selecciona su Service de destino.
Dónde se ejecuta
GitHub Action
Comenta en las pull requests que cambian la arquitectura y actualiza ese mismo comentario en cada push. Las que no tocan la arquitectura quedan en silencio.
Bitbucket Pipelines
El mismo comportamiento como paso de pipeline: en silencio si no cambió nada, y un único comentario siempre actualizado si cambió.
Línea de comandos
Imprime la arquitectura como Mermaid, JSON o un documento Markdown completo, e informa de lo que cambió desde una revisión de git, leyendo la base directamente de git sin tocar tu directorio de trabajo.
Un ARCHITECTURE.md vivo
Un workflow regenera el documento en cada push a main y lo commitea de vuelta si cambió, así que nadie tiene que acordarse de actualizarlo.
Cómo está construido
Un pequeño monorepo en TypeScript. El flujo es: archivos, extractor, modelo de arquitectura, diff contra la base y, al final, un informe en Markdown con un diagrama Mermaid.
Añadir un formato significa escribir un extractor, una comprobación sobre la ruta más una función que devuelve componentes y dependencias, registrarlo y cubrirlo con un test. No hace falta cambiar nada más.
@edgaragg/trazo-core
La librería: extractores que leen archivos hacia un modelo, diff de modelos y renderizado a Mermaid y Markdown. Nunca toca el sistema de archivos, así que es fácil de probar y reutilizar.
@edgaragg/trazo-cli
La línea de comandos. Encuentra los archivos, los lee del disco o de git y llama a core. Incluye también el paso para Bitbucket Pipelines: la misma capa fina, dirigida a la API de Bitbucket en lugar de la de GitHub.
@edgaragg/trazo-action
La GitHub Action, privada porque GitHub la ejecuta directamente desde el repositorio: una capa fina sobre la CLI que publica el comentario. Se distribuye como un bundle commiteado, que reconstruye un hook de pre-commit y verifica el CI.
Dónde está hoy
Trazo está en una fase temprana, pero funciona de principio a fin.
Solo detecta relaciones declaradas, fiel a la idea de no adivinar nunca: un servicio que encuentra su base de datos a través de una variable de entorno no queda enlazado con ella.
En la hoja de ruta:
- Plantillas de CloudFormation y SAM, incluidos los backends de AWS Amplify.
- Un comando de comprobación que haga fallar un build cuando la arquitectura cambió sin actualizar la documentación.
- Un archivo de exclusiones para omitir rutas que son ilustrativas y no reales.
- Descripciones opcionales escritas por un LLM sobre el modelo extraído, con tu propia API key.
Contacto
¿Hablamos?
Abierto a conversaciones sobre arquitectura, plataformas y equipos. La forma más rápida de contactarme es LinkedIn.
