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

id	title	type	status	date	deciders	tags
ADR-001	Stack Tecnologico Base	ADR	Accepted	2026-01-04	@Tech-Lead @Backend-Agent @Frontend-Agent	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
• TypeORM Documentation
• FastAPI Documentation
• React Documentation
• Docker Documentation

---

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