Saltar a contenido

0002. Arquitectura: modular por dominio, con las reglas de dependencia del frontend

Estado: Propuesto; complementado por ADR 0003, ADR 0004 Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): lib/, test/ Complementado por: ADR 0003 — árbol concreto de carpetas de lib/ y test/; ADR 0004 — reglas del repositorio como frontera de datos

Contexto

La app reúne varios dominios (sesión, cartera de clientes, agenda y visitas, pedidos, requerimientos y, después, cobros) servidos por microservicios distintos que todavía cambian. El core-frontend ya resolvió el mismo problema con una arquitectura modular por dominio (su ADR 0001) y los servicios con un paquete por dominio (ADR 0002 de fuerza de ventas). Quien pase de la web a la app no debería reaprender dónde va cada cosa. La diferencia real es que la app tendrá que trabajar sin conexión, aunque la primera versión no lo haga.

Decisión

  • Cinco niveles en lib/, los mismos que la web: app/ (arranque, router, tema, shell), core/ (infraestructura sin negocio), shared/ (negocio transversal), modules/<dominio>/ (una capacidad completa) y pages/ (pantallas que combinan módulos, p. ej. «Mi ruta»).
  • Las dependencias van hacia abajo: app → pages → modules → shared → core. Un módulo nunca importa otro módulo: lo que coordina dos va a pages/ o app/; un concepto que usan varios sube a shared/.
  • API pública por módulo: cada uno expone lo que ofrece desde <modulo>.dart (equivale al index.ts); de fuera no se importan sus archivos internos.
  • Repositorio por módulo, la única capa que se agrega a la web. El frontend descarta repositories/ porque lee directo del backend. En la app el repositorio es la costura para sumar la base local sin tocar providers ni pantallas (ADR 0004). Es el único que conoce dio.
  • Flujo de datos:
Widget → provider (Riverpod) → repositorio del módulo → API del módulo → Dio del servicio
                                         (después: base local y cola de salida, ADR 0004)
  • Los widgets no hacen HTTP; los providers no conocen dio.

Alternativas descartadas

  • Clean Architecture completa (domain/, use_cases/, entidades separadas de los DTO) — más indirección de la que el equipo necesita; el repositorio basta para aislar el origen de los datos.
  • Providers que llaman a la API directamente, como la web — al llegar el modo sin conexión habría que reescribir cada provider.
  • Organizar por capa técnica (screens/, services/, models/ globales) — dispersa cada dominio, como descartaron la web y los servicios.
  • Feature-first sin shared/ ni pages/ — termina con módulos que se importan entre sí para armar la pantalla del día.

Consecuencias

  • Un microservicio nuevo tiene plantilla: cliente en core/network/ y módulo en modules/<dominio>/ (ADR 0003).
  • Mientras la app trabaje en línea, el repositorio parece una capa de paso; se acepta por lo que ahorra después.
  • Ninguna herramienta verifica todavía las reglas de imports; se revisan en el PR. Si se rompen, se agrega una regla (p. ej. import_lint).
  • Hay que vigilar que shared/ no se vuelva un cajón de sastre.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.