betting-analytics/docs/97-adr/ADR-001-stack-tecnologico.md

---
id: "ADR-001"
title: "Stack Tecnologico Base"
type: "ADR"
status: "Accepted"
date: "2026-01-04"
deciders: ["@Tech-Lead", "@Backend-Agent", "@Frontend-Agent"]
tags: ["architecture", "stack", "backend", "frontend", "database"]
---

# ADR-001: Stack Tecnologico Base

**Status:** Accepted
**Date:** 2026-01-04
**Deciders:** @Tech-Lead, @Backend-Agent, @Frontend-Agent

---

## Context

El proyecto Betting Analytics requiere un stack tecnologico que soporte:

1. **API REST** para servir datos a clientes web y movil
2. **Base de datos relacional** para almacenar datos estructurados de eventos, usuarios y predicciones
3. **Autenticacion segura** basada en tokens
4. **Servicio de ML** independiente para modelos predictivos
5. **Frontend web** moderno y reactivo
6. **Containerizacion** para portabilidad y despliegue consistente

### Constraints

- Equipo con experiencia en TypeScript/JavaScript
- Necesidad de desarrollo rapido (MVP en 3 meses)
- Presupuesto limitado para infraestructura
- Escalabilidad horizontal requerida a futuro

### Forces

- Productividad vs Rendimiento
- Familiaridad vs Mejor herramienta
- Monolito vs Microservicios
- SQL vs NoSQL

---

## Decision

### Backend: NestJS + TypeORM

**Seleccion:** NestJS v10 con TypeORM sobre PostgreSQL

**Razones:**
- Arquitectura modular y escalable out-of-the-box
- TypeScript nativo con decoradores
- Integracion sencilla con TypeORM para ORM
- Ecosistema maduro de middleware (Passport, Guards, Interceptors)
- Documentacion excelente
- Facil testing con modulos de prueba

**Alternativas consideradas:**

| Alternativa | Pros | Contras | Decision |
|-------------|------|---------|----------|
| Express + TypeScript | Ligero, flexible | Sin estructura, mas setup manual | Rechazado |
| Fastify | Muy rapido | Ecosistema menor, menos decoradores | Rechazado |
| Hono | Ultraligero, Edge-ready | Muy nuevo, menos integraciones | Rechazado |

### Base de Datos: PostgreSQL

**Seleccion:** PostgreSQL v15+

**Razones:**
- Datos altamente relacionales (usuarios, eventos, predicciones)
- Soporte nativo para JSON/JSONB para flexibilidad
- Extensiones utiles (PostGIS si se necesita geolocalizacion)
- Maduro, estable, open source
- Excelente integracion con TypeORM

**Alternativas consideradas:**

| Alternativa | Pros | Contras | Decision |
|-------------|------|---------|----------|
| MySQL | Familiar, rapido | Menos features, JSON limitado | Rechazado |
| MongoDB | Flexible schema | No ideal para datos relacionales | Rechazado |
| CockroachDB | Distribuido | Complejidad innecesaria para MVP | Rechazado |

### ORM: TypeORM

**Seleccion:** TypeORM v0.3

**Razones:**
- Decoradores que integran con clases de entidad
- Integracion nativa con NestJS
- Soporte para migraciones
- Repository pattern

**Alternativas consideradas:**

| Alternativa | Pros | Contras | Decision |
|-------------|------|---------|----------|
| Prisma | Type-safe, moderno | Schema separado, menos decoradores | Rechazado |
| MikroORM | Performante | Menos adopcion, curva de aprendizaje | Rechazado |
| Drizzle | Ligero, moderno | Muy nuevo, menos features | Rechazado |

### Autenticacion: JWT + Passport

**Seleccion:** JWT con Passport.js

**Razones:**
- Stateless, escalable horizontalmente
- Integracion nativa con NestJS via @nestjs/passport
- Estrategias modulares (local, JWT, OAuth futuro)
- Estandar de la industria

**Alternativas consideradas:**

| Alternativa | Pros | Contras | Decision |
|-------------|------|---------|----------|
| Sessions | Simple, seguro | Stateful, dificil escalar | Rechazado |
| Auth0/Clerk | Managed, features | Costo, vendor lock-in | Rechazado |
| Supabase Auth | Integrado | Dependencia de Supabase | Rechazado |

### Frontend: React + Vite

**Seleccion:** React v18 con Vite

**Razones:**
- Biblioteca UI mas popular
- Ecosistema enorme de componentes
- Vite ofrece desarrollo rapido con HMR
- TypeScript first-class
- Zustand para estado simple y efectivo

**Alternativas consideradas:**

| Alternativa | Pros | Contras | Decision |
|-------------|------|---------|----------|
| Next.js | SSR, file routing | Overhead para SPA, complejidad | Rechazado |
| Vue 3 | Sencillo, reactivo | Menos ecosistema, menos familiaridad | Rechazado |
| Svelte | Performante, simple | Ecosistema pequeno | Rechazado |

### ML Engine: Python + FastAPI

**Seleccion:** Python 3.11 con FastAPI

**Razones:**
- Python es el estandar para ML
- FastAPI es moderno, rapido, async
- Integracion sencilla con scikit-learn, pandas
- Documentacion automatica con OpenAPI
- Tipado con Pydantic

**Alternativas consideradas:**

| Alternativa | Pros | Contras | Decision |
|-------------|------|---------|----------|
| Flask | Simple, maduro | Sincrono, menos moderno | Rechazado |
| Django | Batteries included | Overkill para servicio ML | Rechazado |
| Node.js (TensorFlow.js) | Unificar stack | ML en JS es limitado | Rechazado |

### Containerizacion: Docker

**Seleccion:** Docker + Docker Compose

**Razones:**
- Portabilidad entre ambientes
- Consistencia desarrollo/produccion
- Orquestacion sencilla con Compose
- Preparado para Kubernetes futuro

---

## Consequences

### Positivas

1. **Productividad:** NestJS y React permiten desarrollo rapido con TypeScript
2. **Escalabilidad:** Servicios separados pueden escalar independientemente
3. **Mantenibilidad:** Codigo tipado reduce bugs, arquitectura modular facilita cambios
4. **Contratacion:** Stack popular facilita onboarding de nuevos agentes
5. **Documentacion:** Swagger automatico en NestJS, OpenAPI en FastAPI

### Negativas

1. **Complejidad:** Multiples servicios requieren orquestacion
2. **Overhead:** TypeORM puede ser mas lento que queries raw
3. **Aprendizaje:** FastAPI separado del stack principal
4. **Deployment:** Multiples containers a gestionar

### Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Performance TypeORM | Media | Medio | Optimizar queries, indices |
| Complejidad Docker | Baja | Bajo | Documentacion, scripts |
| Curva FastAPI | Media | Bajo | Documentacion, templates |

---

## Compliance

Este ADR cumple con:
- Principios de arquitectura del proyecto
- Restricciones de recursos del equipo
- Timeline de MVP

---

## References

- [NestJS Documentation](https://docs.nestjs.com)
- [TypeORM Documentation](https://typeorm.io)
- [FastAPI Documentation](https://fastapi.tiangolo.com)
- [React Documentation](https://react.dev)
- [Docker Documentation](https://docs.docker.com)

---

## Changelog

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-01-04 | @Tech-Lead | Initial decision |

---

**Document:** ADR-001
**Project:** Betting Analytics
**Status:** Accepted
**Date:** 2026-01-04