trading-platform/docs/97-adr/ADR-002-monorepo.md

id	title	type	project	version	updated_date
ADR-002-monorepo	Estructura Monorepo	Documentation	trading-platform	1.0.0	2026-01-04

ADR-002: Estructura Monorepo

Estado: Aceptado Fecha: 2025-12-06 Decisores: Tech Lead, Arquitecto Relacionado: ADR-001

---

Contexto

Trading Platform requiere gestionar múltiples aplicaciones interconectadas:

• Backend API (Express + TypeScript)
• Frontend Web (React + TypeScript)
• ML Engine (FastAPI + Python)
• Database (PostgreSQL schemas y migrations)

Necesitamos una estrategia que permita:

1. Compartir código TypeScript entre frontend y backend (DTOs, validaciones, tipos)
2. Despliegues coordinados cuando hay cambios en contratos API
3. Versionado unificado del proyecto
4. Configuración compartida (ESLint, TypeScript, Prettier)
5. Gestión simplificada de dependencias

El equipo tiene experiencia con monorepos en proyectos previos (Gamilit, TradingAgent).

---

Decisión

Adoptamos una estructura monorepo con la siguiente organización:

trading-platform/
├── apps/
│   ├── backend/          # Express.js API
│   ├── frontend/         # React SPA
│   ├── ml-engine/        # FastAPI ML service
│   └── database/         # DDL, migrations, seeds
├── packages/
│   ├── shared-types/     # TypeScript types compartidos
│   ├── validation/       # Zod schemas compartidos
│   └── utils/           # Utilidades compartidas
├── scripts/
│   ├── dev.sh           # Script para iniciar todos los servicios
│   └── test-all.sh      # Script para correr tests de todas las apps
└── package.json         # Workspace root

Herramienta de Workspace

• npm workspaces (nativo en npm 7+)
• No usamos Turborepo/Nx para evitar complejidad innecesaria en MVP

Comandos de Workspace

{
  "scripts": {
    "dev": "npm run dev --workspaces",
    "build": "npm run build --workspaces",
    "test": "npm run test --workspaces",
    "lint": "npm run lint --workspaces"
  }
}

---

Consecuencias

Positivas

1. DRY (Don't Repeat Yourself): DTOs y tipos compartidos entre frontend/backend eliminan duplicación
2. Type Safety End-to-End: Cambios en API se reflejan inmediatamente en frontend vía TypeScript
3. Atomic Commits: Un PR puede actualizar backend + frontend + tipos en un solo commit
4. Configuración Centralizada: ESLint, Prettier, tsconfig compartidos
5. Dependencias Centralizadas: Un solo package-lock.json para gestionar versiones
6. CI/CD Simplificado: Un solo pipeline para todo el proyecto
7. Developer Experience: npm run dev inicia todo el stack local

Negativas

1. Tamaño del Repositorio: Crece más rápido que repos separados
2. Tiempos de CI: Requiere caching inteligente para evitar rebuilds innecesarios
3. Permisos Granulares: No podemos dar acceso solo a frontend/backend por separado
4. Learning Curve: Nuevos devs deben entender la estructura completa
5. Git Conflicts: Mayor probabilidad de conflictos en package.json

Riesgos y Mitigaciones

Riesgo	Mitigación
CI lento	GitHub Actions cache + build paralelo
Coupling excesivo	Linting rules para prevenir imports circulares
Complejidad	Documentar scripts y estructura en README

---

Alternativas Consideradas

1. Multi-Repositorio (Polyrepo)

• Pros: Independencia total, permisos granulares
• Contras: Duplicación de código, sincronización manual de tipos, versionado complejo
• Decisión: ❌ Descartada - Overhead de sincronización entre repos

2. Turborepo

• Pros: Build caching avanzado, pipelines optimizados
• Contras: Complejidad adicional, curva de aprendizaje
• Decisión: ❌ Descartada - Overkill para equipo pequeño en fase MVP

3. Nx Monorepo

• Pros: Herramientas completas, scaffolding, dependency graph
• Contras: Muy opinionado, configuración compleja
• Decisión: ❌ Descartada - Demasiada abstracción para nuestras necesidades

4. Lerna

• Pros: Tradicional, buena documentación
• Contras: Mantenimiento limitado, npm workspaces nativo lo reemplaza
• Decisión: ❌ Descartada - npm workspaces es suficiente

---

Referencias

• npm Workspaces Documentation
• Monorepo Best Practices
• TypeScript Project References