rckrdmrd
c1b5081208
ML Engine Updates: - Updated BTCUSD with Polygon API data (2024-2025): 215,699 new records - Re-trained all ML models: Attention (R²: 0.223), Base, Metamodel (87.3% confidence) - Backtest results: +176.71R profit with aggressive_filter strategy Documentation Consolidation: - Created docs/99-analisis/_MAP.md index with 13 new analysis documents - Consolidated inventories: removed duplicates from orchestration/inventarios/ - Updated ML_INVENTORY.yml with BTCUSD metrics and training results - Added execution reports: FASE11-BTCUSD, correction issues, alignment validation Architecture & Integration: - Updated all module documentation with NEXUS v3.4 frontmatter - Fixed _MAP.md indexes across all folders - Updated orchestration plans and traces Files: 229 changed, 5064 insertions(+), 1872 deletions(-) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
---
|
|
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
|
|
|
|
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
|
|
```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)
|