Architecture and coding principles
Cross-project defaults that every module must follow (DOC-010).
Source: docs/architecture/DOC-010-architecture-coding-principles.md
DOC-010: Principios de arquitectura y codificación (stack-agnóstico)
Estado
Accepted (seed).
No fija tecnologías. El stack (lenguaje, framework, DB, hosting) se decide después con ADRs de tecnología.
Propósito
Principios que valen antes de saber si el backend es Nest, Django, Go, Rails, etc., o el cliente es web, mobile o CLI.
Fuente operativa: .cursor/rules/seed-code-patterns.mdc.
1. Separación de responsabilidades (servidor / dominio)
| Principio | Qué implica |
|---|---|
| Módulos por frontera de negocio | Organizar por bounded context / capacidad, no por un solo “saco” técnico. Preferir un deployable modular; partir en servicios solo con ADR y necesidad real. |
| Dominio aislado de detalles | Reglas de negocio no dependen de DB, HTTP, colas ni vendors. Adaptadores hacia afuera. |
| Casos de uso explícitos | Orquestación de la aplicación fuera de la capa de entrega (HTTP, CLI, jobs). |
| Persistencia detrás de puertos | El dominio no habla el dialecto del ORM/driver. |
| Sin acoplamiento cruzado | Un módulo no usa el almacén interno de otro. Comunicación: contratos públicos, orquestación o eventos. |
Capas conceptuales (nombres ilustrativos)
No son carpetas obligatorias ni de un framework. El proyecto las mapea a su layout cuando elija stack.
| Capa | Responsabilidad |
|---|---|
| Dominio | Entidades, reglas, puertos, eventos de negocio |
| Aplicación | Casos de uso / services de aplicación |
| Adaptadores de salida | DB, email, pagos, buses |
| Adaptadores de entrada | HTTP, GraphQL, gRPC, CLI, workers |
En módulos trivialmente CRUD se puede aligerar; no abandonar el aislamiento del dominio en módulos con reglas.
ADR: ADR-010.
2. Organización de clientes (UI / apps)
| Principio | Qué implica |
|---|---|
| Por feature / capacidad | Agrupar lo de una capacidad de producto; no solo components/ vs utils/ globales. |
| Datos vs presentación | Separar “cómo se obtienen/gestionan los datos” de “cómo se pintan”. |
| Un acceso al backend | Un módulo/cliente de API compartido; evitar llamados dispersos e inconsistentes. |
| Validación cerca del input | Reglas de forma/entrada junto a la feature que las usa. |
| Estados de interfaz consistentes | Loading, vacío, error y éxito planificados — no improvisar solo texto “cargando…”. |
Formularios (comportamiento, no framework)
- Errores de validación visibles junto al campo, no solo aviso global.
- Al corregir el valor, limpiar el error de ese campo.
- Avisos tipo toast/snackbar para resultado de operación remota, no para cada required vacío.
- Si hay cambios sin guardar, confirmar antes de salir.
El naming de carpetas (features/, hooks/, etc.) lo decide el ADR de UI del proyecto.
ADR: ADR-011.
3. Contratos de interfaz (API)
Principios independientes del framework:
- Elegir un estilo de API y documentarlo (REST, GraphQL, gRPC, etc.) vía ADR.
- Contrato primero (spec versionada en el repo) antes o junto al código de endpoints.
- Versionado explícito de la API pública.
- Convenciones de nombres alineadas al glosario de dominio.
- Paginación / filtrado uniformes si hay listados.
- Operaciones críticas: idempotencia cuando corresponda.
- Correlación / request id para tracing.
- Errores estructurados y predecibles para clientes.
No asumir REST ni un path concreto hasta el ADR de API del proyecto.
ADR: ADR-012.
4. Testing
Pirámide (herramientas = ADR de stack):
- Unit — dominio y casos de uso; sin DB ni red.
- Integration — frontera con DB, cola, API real o testcontainers.
- Contract — cuando hay varios clientes del mismo contrato.
- E2E — pocos flujos P0.
Gates:
- Tests en el mismo change que el código.
- Fase Tests obligatoria en
tasks.md(Spec Kit / OpenSpec). - CI verifica calidad antes de merge a la rama base.
ADR: ADR-013 · .specify/memory/testing.md.
5. Eventos de negocio
- Representan hechos (pasado): algo ocurrió.
- Versionar el shape del evento.
- Emitir después de persistir con éxito (cuando hay transacción).
- Empezar in-process / en el mismo proceso si hay un solo deployable; bus externo solo con ADR.
- Catálogo documentado cuando exista dominio formal.
- Coordinan entre módulos; no reemplazan consistencia dentro de un agregado.
ADR: ADR-014.
6. Secretos y configuración
- Secretos nunca en git ni hardcodeados.
- Config por entorno; fallar al arrancar si falta lo crítico.
- Plantillas locales sin secretos reales (p. ej.
.env.example). - CI/CD usa el secret store del proveedor.
- Mínimo privilegio.
ADR: ADR-015.
7. Naming e idioma
| Superficie | Convención |
|---|---|
| Código, APIs, commits | inglés |
| Archivos, símbolos y JSON | Ver .specify/memory/coding-style.md |
| Chat con humano / prosa de specs | español |
| Commits | Conventional Commits |
IDs y enums: definilos en el ADR de dominio/datos del proyecto.
8. Prohibido (siempre)
- Lógica de negocio en la capa de entrega (handlers HTTP, pantallas “tontas” que en realidad deciden reglas).
- Acceso interno al almacén de otro módulo/contexto.
- Secretos en el repositorio.
- Features sin spec (DOC-013).
- Cambiar arquitectura sin ADR.
- Dependencias nuevas sin justificación en el change.
9. Qué se decide más tarde
Lenguaje, framework, ORM, monorepo vs repo único, REST vs GraphQL, cloud, design system de marca, multi-tenant del producto, glosario. Todo eso = ADRs del proyecto al arrancar.
Referencias
- Constitution:
.specify/memory/constitution.md - Code patterns:
.cursor/rules/seed-code-patterns.mdc - AI-SDLC:
docs/development/DOC-013-ai-sdlc-hybrid-workflow.md