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) ypages/(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 apages/oapp/; un concepto que usan varios sube ashared/. - API pública por módulo: cada uno expone lo que ofrece desde
<modulo>.dart(equivale alindex.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 conocedio. - 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/nipages/— 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 enmodules/<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.