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

# ADR-002: Estructura Monorepo

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

---

## Contexto

OrbiQuant IA 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
```json
{
  "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](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
- [Monorepo Best Practices](https://monorepo.tools/)
- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)