# ADR-001: Stack Tecnologico

**Fecha:** 2025-12-05
**Estado:** ✅ Aceptado
**Deciders:** Tech Lead, CTO

---

## Contexto

OrbiQuant IA necesita un stack tecnologico que permita:
1. Desarrollo rapido del MVP (8 semanas)
2. Escalabilidad para crecimiento futuro
3. Integracion con APIs de trading y ML
4. Experiencia de usuario fluida en web y movil
5. Mantenibilidad a largo plazo

El equipo tiene experiencia previa con proyectos similares (Gamilit, TradingAgent) usando TypeScript y Python.

---

## Decision

### Frontend
- **React 18** + **TypeScript 5** como framework principal
- **Vite** como build tool (HMR rapido, ESM nativo)
- **Tailwind CSS** para estilos (utility-first, dark mode)
- **Zustand** para state management (simple, sin boilerplate)
- **TanStack Query** para data fetching (cache, refetch, optimistic updates)
- **Lightweight Charts** para graficos de trading (TradingView quality)

### Backend API
- **Express.js 4.18** + **TypeScript** para API REST
- **Zod** para validacion de schemas
- **JWT** + **Passport.js** para autenticacion
- **PostgreSQL 15** como base de datos principal
- **Redis 7** para cache y sesiones

### ML Engine
- **Python 3.11** + **FastAPI** para API de predicciones
- **XGBoost** para modelos de ML
- **Pandas/NumPy** para procesamiento de datos

### Servicios Externos
- **Stripe** para pagos
- **Twilio** para SMS/WhatsApp
- **Nodemailer** para emails

---

## Alternativas Consideradas

### Frontend Framework

| Opcion | Pros | Contras | Decision |
|--------|------|---------|----------|
| **React** | Ecosistema maduro, equipo experimentado | Mas boilerplate que alternativas | ✅ Elegido |
| Next.js | SSR, routing integrado | Complejidad innecesaria para SPA | ❌ |
| Vue.js | Curva de aprendizaje suave | Menos experiencia del equipo | ❌ |
| Svelte | Performance, menos codigo | Ecosistema menos maduro | ❌ |

### Backend Framework

| Opcion | Pros | Contras | Decision |
|--------|------|---------|----------|
| **Express.js** | Flexible, probado, conocido | Sin estructura opinionada | ✅ Elegido |
| NestJS | Estructura, decoradores | Overhead para MVP | ❌ |
| Fastify | Mas rapido que Express | Menos plugins | ❌ |
| Hono | Ultra ligero | Muy nuevo | ❌ |

### Base de Datos

| Opcion | Pros | Contras | Decision |
|--------|------|---------|----------|
| **PostgreSQL** | ACID, JSONB, extensiones | Mas complejo que NoSQL | ✅ Elegido |
| MongoDB | Flexible schema | No ACID por defecto | ❌ |
| MySQL | Popular, simple | Menos features que Postgres | ❌ |

### State Management

| Opcion | Pros | Contras | Decision |
|--------|------|---------|----------|
| **Zustand** | Simple, TypeScript, sin boilerplate | Menos features que Redux | ✅ Elegido |
| Redux Toolkit | Feature completo, devtools | Boilerplate, complejidad | ❌ |
| Jotai | Atomico, simple | Menos popular | ❌ |
| Recoil | De Facebook | Futuro incierto | ❌ |

---

## Consecuencias

### Positivas

1. **Velocidad de desarrollo**: El equipo ya conoce el stack
2. **Type safety**: TypeScript en frontend y backend reduce errores
3. **Reutilizacion**: Codigo de Gamilit y TradingAgent reutilizable
4. **Contratacion**: Stack popular, facil encontrar desarrolladores
5. **Comunidad**: Amplia documentacion y soporte

### Negativas

1. **JavaScript fatigue**: Muchas dependencias npm a mantener
2. **Dos lenguajes**: TypeScript para API, Python para ML
3. **Express flexibility**: Requiere mas disciplina en estructura

### Riesgos

1. **Dependencias desactualizadas**: Mitigacion con Renovate/Dependabot
2. **Breaking changes en React 19**: Mantenerse en v18 hasta estabilizar

---

## Referencias

- [React 18 Release Notes](https://react.dev/blog/2022/03/29/react-v18)
- [Zustand Documentation](https://zustand-demo.pmnd.rs/)
- [TanStack Query](https://tanstack.com/query)
- [Express.js Best Practices](https://expressjs.com/en/advanced/best-practice-security.html)
- [PostgreSQL vs MySQL](https://www.postgresql.org/about/)
