rckrdmrd
094493625c
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
231 lines
6.6 KiB
Markdown
231 lines
6.6 KiB
Markdown
---
|
|
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
|