joshfinnie/mermaid-gen

El objetivo de estos diagramas es que alguien nuevo en el repositorio pueda confiar en ellos. Un diagrama que inventa un servicio o ignora la base de datos es peor que ninguno, por lo que todo aquí se basa en dibujar lo que el código realmente muestra.

1. Reconocimiento antes de dibujar

Ejecuta scripts/survey.py (las rutas en este skill son relativas a su carpeta) contra la raíz del repositorio:

python3 scripts/survey.py /ruta/al/repo > /tmp/mermaid-survey.txt

Enumera los módulos con recuentos de archivos, manifiestos, puntos de entrada, servicios externos encontrados en las dependencias declaradas, fuentes del modelo de datos y el grafo de importaciones entre módulos con recuentos. Cada arista de importación proviene de sentencias de importación reales, así que usa esas aristas como la columna vertebral del diagrama de arquitectura. Si un módulo contiene la mayor parte del código y necesita dividirse, vuelve a ejecutarlo con --depth 3.

Luego lee lo que el script no puede ver:

• el README y cualquier documentación existente, para los nombres que el equipo ya usa
• los puntos de entrada, para ver qué se ejecuta como su propio proceso (servidores, workers, CLIs, trabajos cron, lambdas)
• la configuración de despliegue (Dockerfile, archivos compose, fly.toml, serverless/CDK, Terraform), para ver qué se despliega por separado y con qué se comunica
• las llamadas que cruzan un límite de proceso: clientes HTTP y URLs base, publicadores y consumidores de colas, SDKs de clientes para servicios externos

Mantén una nota breve de qué archivo respalda cada caja y flecha. Se convertirá en la lista de Fuentes en el resultado.

Si el usuario solicita solo un diagrama ("un diagrama ER de nuestra base de datos"), haz solo ese, pero primero haz el reconocimiento.

2. Resumen de arquitectura

Dibuja un flowchart de las piezas desplegables y los módulos dentro de ellas, más los almacenes de datos y servicios externos que utilizan. Apunta a 6 a 20 nodos. Un repositorio más grande se agrupa en subgrafos por unidad desplegable, no en más cajas.

• Los nodos son cosas que un desarrollador nombraría: "Servidor API", "aplicación web", "consumidor firehose", "PostgreSQL", "Stripe". Usa los nombres del equipo del README o nombres de paquetes.
• Las flechas apuntan de quien llama a quien es llamado, e indican cómo cuando cruza un proceso ("REST /api", "SQL", "Subida S3"). Deja las importaciones dentro del proceso sin etiquetar.
• Omite lo que no explica el sistema: módulos de utilidad que todos importan, paquetes solo de tipos, pruebas, scripts de compilación. Menciónalos en el texto si son importantes.
• No dibujes lo que no puedas señalar. Si sospechas una conexión pero no encuentras el código para ella, déjala fuera y menciónalo en el texto.

Las convenciones de forma y estilo están en references/diagram-guide.md.

3. Modelo de datos

Dibuja un erDiagram solo cuando el reconocimiento enumere fuentes de modelo de datos; si no hay ninguna, menciónalo en una oración y omítelo. No infieras tablas a partir de tipos de API o nombres de variables, porque un esquema adivinado parece tan autoritativo como uno real.

• Las migraciones son la verdad cuando existen. Aplícalas en orden, para que los ALTER, DROP y renombres posteriores ganen. Si los modelos ORM discrepan de las migraciones, sigue las migraciones y señala la discrepancia.
• Dos conjuntos de migraciones (por ejemplo, un viejo supabase/migrations/ y una carpeta drizzle/ activa) generalmente significa que uno está desactualizado. Sigue al que apunta el comando de migración de la aplicación o la configuración del ORM (drizzle.config.*, prisma/schema.prisma, el script migrate en package.json), y nombra el desactualizado en el texto.
• Muestra las claves y las columnas que identifican una fila: claves primarias, claves foráneas, columnas únicas y algunas columnas que un lector necesita para reconocer la entidad. Omite marcas de tiempo y otras columnas administrativas a menos que sean importantes.
• Lee la cardinalidad de las restricciones. Una clave foránea no nula es exactamente una en el lado padre, una anulable es cero o una, y una clave foránea única hace que la relación sea uno a uno. Etiqueta cada relación con una frase verbal corta.
• Pasadas unas 15 entidades, divide el diagrama por dominio en lugar de dibujar una sola pared de tablas.

4. Escribe el archivo

Escribe docs/architecture.md, o actualízalo si existe. Si el repositorio guarda la documentación en otro lugar, sigue eso, y si el usuario nombró una ruta, usa la suya. Para cada diagrama:

## Arquitectura

Dos o tres oraciones sobre lo que muestra el diagrama y cualquier cosa que omita.

<!-- mermaid-gen:start architecture -->
```mermaid
flowchart LR
  ...
```
<!-- mermaid-gen:end architecture -->

**Fuentes:** `cmd/server/main.go`, `internal/handler/`, `fly.toml`

Los comentarios marcadores permiten que una ejecución posterior reemplace solo el diagrama sin tocar el texto editado manualmente. Al actualizar un archivo existente, cambia solo lo que está entre marcadores, más la explicación y las fuentes directamente alrededor de ellos.

5. Verifica que se renderice

Ejecuta scripts/lint_mermaid.py en el archivo:

python3 scripts/lint_mermaid.py /ruta/al/repo/docs/architecture.md

Detecta los errores que más a menudo rompen la renderización: caracteres especiales en etiquetas sin comillas, palabras reservadas como end como ids de nodo, un subgraph sin cerrar, y relaciones o atributos ER mal formados. Corrige cada error antes de terminar. Si mmdc (mermaid-cli) está instalado, renderiza también con él.

Termina informando al usuario dónde está el archivo, qué cubre cada diagrama y cualquier cosa que hayas omitido o no hayas podido confirmar.