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)

PrincipioQué implica
Módulos por frontera de negocioOrganizar 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 detallesReglas de negocio no dependen de DB, HTTP, colas ni vendors. Adaptadores hacia afuera.
Casos de uso explícitosOrquestación de la aplicación fuera de la capa de entrega (HTTP, CLI, jobs).
Persistencia detrás de puertosEl dominio no habla el dialecto del ORM/driver.
Sin acoplamiento cruzadoUn 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.

CapaResponsabilidad
DominioEntidades, reglas, puertos, eventos de negocio
AplicaciónCasos de uso / services de aplicación
Adaptadores de salidaDB, email, pagos, buses
Adaptadores de entradaHTTP, 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)

PrincipioQué implica
Por feature / capacidadAgrupar lo de una capacidad de producto; no solo components/ vs utils/ globales.
Datos vs presentaciónSeparar “cómo se obtienen/gestionan los datos” de “cómo se pintan”.
Un acceso al backendUn módulo/cliente de API compartido; evitar llamados dispersos e inconsistentes.
Validación cerca del inputReglas de forma/entrada junto a la feature que las usa.
Estados de interfaz consistentesLoading, 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):

  1. Unit — dominio y casos de uso; sin DB ni red.
  2. Integration — frontera con DB, cola, API real o testcontainers.
  3. Contract — cuando hay varios clientes del mismo contrato.
  4. 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

SuperficieConvención
Código, APIs, commitsinglés
Archivos, símbolos y JSONVer .specify/memory/coding-style.md
Chat con humano / prosa de specsespañol
CommitsConventional 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