Digito Architecture

Documentación de la arquitectura de Digito y de sus procesos automatizados en LikeC4, y de las reglas de ingeniería que aplican transversalmente a la organización.

Cómo está organizado

El repositorio se organiza por ciclo de vida del documento, no por formato. Hay cuatro, y se mantienen de forma distinta:

Directorio	Qué contiene	Ciclo de vida
arquitectura/	El modelo LikeC4: sistemas, contenedores, vistas y procesos	Estado actual: mutable, siempre sobrescrito
ingenieria/	Principios, estándares, Definition of Done	Normas: versionadas, con dueño
decisiones/	ADRs de alcance organizacional	Decisiones: inmutables, se agregan al final
boletines/	Qué cambió, semana por semana	Noticias: inmutables, fechadas

Documentamos en español, con un matiz por audiencia: arquitectura/ completo, porque es lo que una autoridad puede requerir y traducirlo después es trabajo, demora y riesgo; en ingenieria/, prosa en español y sustantivos técnicos en inglés sin traducir. Los identificadores del modelo se quedan como aparecen en las herramientas.

Empezar

Hace falta Node 24 (nvm use). Una vez:

npm install

Comando	Qué hace
npm run dev:model	Visualizador de los diagramas, con recarga en caliente
npm run dev	Sitio completo: markdown con búsqueda + diagramas embebidos
npm run dev:stop	Detiene el sitio. Astro 7 lo corre como demonio, así que npm run dev devuelve el prompt y el servidor sigue vivo
npm run check	Valida el modelo y su formato. Es lo que corre CI en cada pull request
npm run format	Arregla el formato de los .c4
npm run build	Sitio estático en sitio/dist/
npm run build:standalone	Un HTML autocontenido con todas las vistas

Arquitectura

El modelo vive en arquitectura/*.c4. Todos los archivos se fusionan en un solo modelo, así que la división por archivo es solo para saber dónde editar: landscape.c4 para los sistemas y sus relaciones, sistemas/<sistema>.c4 para los contenedores.

Antes de editar, lee las tres reglas de arquitectura/README.md — sobre todo la primera, que evita relaciones duplicadas en los diagramas.

Procesos

Los procesos automatizados son vistas dinámicas del mismo modelo, en arquitectura/procesos.c4: sus participantes son los contenedores que ya están declarados, así que npm run check rompe si alguien borra o renombra uno que un proceso usa. Todavía no hay ninguno modelado; la forma está en el archivo.

Decisiones (ADR)

Una sola bitácora, en decisiones/, con las decisiones cuyo alcance es la organización completa. Las que caben dentro de un solo proyecto viven en decisiones/ del repositorio de ese proyecto.

Sube aquí si la decisión afecta a más de un repositorio, si crea o cambia una regla de ingenieria/estandares.md, si mueve la frontera de confianza, o si nos compromete frente a un supervisor. En la duda, sube.

cp decisiones/_plantilla.md decisiones/0001-titulo-en-kebab-case.md

Los ADRs son inmutables. No se editan: se marcan como reemplazados y se escribe uno nuevo. Lo que sí cambia es ingenieria/estandares.md, que es la proyección del estado actual de todas esas decisiones.

Boletín semanal

Qué cambió cada semana, en boletines/, un archivo por semana ISO. No es fuente de verdad de nada: describe cambios y enlaza a la fuente.