betting-analytics/docs/00-vision-general/ARQUITECTURA-GENERAL.md

id	title	type	status	version	created_date	updated_date
ARCH-BA	Arquitectura General - Betting Analytics	Architecture	Draft	1.0.0	2026-01-04	2026-01-04

Arquitectura General - Betting Analytics

---

1. VISION ARQUITECTONICA

Principios de Diseno

Principio	Descripcion
Modularidad	Servicios desacoplados con responsabilidades claras
Escalabilidad	Diseno para crecimiento horizontal
Observabilidad	Logs, metricas y trazas integradas
Seguridad	Defense in depth, zero trust
Simplicidad	KISS - Keep It Simple, Stupid

Estilo Arquitectonico

Microservicios Ligeros con comunicacion via REST APIs y eventos.

---

2. DIAGRAMA DE ALTO NIVEL

                                    ┌─────────────────────┐
                                    │   LOAD BALANCER     │
                                    │     (Traefik)       │
                                    └──────────┬──────────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
           ┌────────▼────────┐       ┌────────▼────────┐       ┌────────▼────────┐
           │    FRONTEND     │       │    BACKEND      │       │    ML ENGINE    │
           │  React + Vite   │       │  NestJS API     │       │  FastAPI + ML   │
           │   Port: 80      │◄─────►│  Port: 3090     │◄─────►│  Port: 3093     │
           └─────────────────┘       └────────┬────────┘       └────────┬────────┘
                                              │                         │
                                              │                         │
                                    ┌─────────▼─────────┐               │
                                    │                   │               │
                                    │   PostgreSQL      │◄──────────────┘
                                    │   (Database)      │
                                    │                   │
                                    └───────────────────┘

---

3. COMPONENTES PRINCIPALES

3.1 Frontend (apps/frontend)

Tecnologia: React + TypeScript + Vite

Responsabilidad	Descripcion
UI/UX	Interfaz de usuario para analytics
Dashboards	Visualizacion de datos y metricas
Autenticacion	Login, registro, gestion de sesion
Consumo API	Cliente para Backend API

Estructura:

frontend/
├── src/
│   ├── components/       # Componentes reutilizables
│   ├── pages/            # Paginas de la aplicacion
│   ├── hooks/            # Custom hooks
│   ├── stores/           # Estado global (Zustand)
│   ├── services/         # Clientes API
│   └── types/            # Definiciones TypeScript
└── Dockerfile

3.2 Backend API (apps/backend)

Tecnologia: NestJS + TypeORM + PostgreSQL

Responsabilidad	Descripcion
API REST	Endpoints para todas las operaciones
Autenticacion	JWT, guards, estrategias
ORM	Acceso a base de datos via TypeORM
Validacion	DTOs con class-validator
Negocio	Logica de dominio

Estructura actual:

backend/
├── src/
│   ├── config/           # Configuracion (database, jwt, app)
│   ├── modules/
│   │   └── auth/         # Modulo de autenticacion (placeholder)
│   ├── shared/
│   │   └── types/        # Tipos compartidos
│   ├── app.module.ts     # Modulo principal
│   └── main.ts           # Punto de entrada
├── Dockerfile
├── package.json
├── tsconfig.json
└── service.descriptor.yml

Modulos Planificados:

• auth/ - Autenticacion y autorizacion
• users/ - Gestion de usuarios
• data-ingestion/ - Ingesta de datos
• analytics/ - Logica de analytics
• predictions/ - Integracion con ML
• reports/ - Generacion de reportes

3.3 ML Engine (apps/ml)

Tecnologia: Python + FastAPI + scikit-learn

Responsabilidad	Descripcion
Modelos ML	Entrenamiento y prediccion
API REST	Endpoints para predicciones
Pipeline	Procesamiento de datos
Backtesting	Validacion de modelos

Estructura planificada:

ml/
├── src/
│   ├── models/           # Modelos ML
│   ├── pipelines/        # Pipelines de datos
│   ├── api/              # Endpoints FastAPI
│   └── main.py           # Punto de entrada
├── requirements.txt
└── Dockerfile

---

4. FLUJO DE DATOS

4.1 Flujo de Autenticacion

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Frontend │────►│ Backend  │────►│ Database │     │          │
│          │     │ /auth    │◄────│          │     │          │
│          │◄────│          │     │          │     │          │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
   Login           Validate         Query            Response
   Request         JWT              User             with Token

4.2 Flujo de Analytics

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Frontend │────►│ Backend  │────►│ Database │
│ Dashboard│     │ /api     │     │ Query    │
│          │◄────│          │◄────│ Data     │
└──────────┘     └──────────┘     └──────────┘
   Request         Process          Fetch
   Data            & Aggregate      Historical

4.3 Flujo de Predicciones

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Frontend │────►│ Backend  │────►│ ML Engine│────►│ Database │
│          │     │          │     │ /predict │     │          │
│          │◄────│          │◄────│          │◄────│          │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
   Request         Orchestrate      Run Model       Get Features
   Prediction      Call             Predict         Historical

---

5. MODELO DE DATOS

5.1 Entidades Principales (Planificadas)

┌────────────────┐     ┌────────────────┐     ┌────────────────┐
│     Users      │     │     Events     │     │   Predictions  │
├────────────────┤     ├────────────────┤     ├────────────────┤
│ id (UUID)      │     │ id (UUID)      │     │ id (UUID)      │
│ email          │     │ sport          │     │ event_id (FK)  │
│ password_hash  │     │ league         │     │ user_id (FK)   │
│ name           │     │ home_team      │     │ predicted      │
│ role           │     │ away_team      │     │ confidence     │
│ created_at     │     │ start_time     │     │ actual_result  │
│ updated_at     │     │ status         │     │ created_at     │
└────────────────┘     │ odds_home      │     └────────────────┘
                       │ odds_draw      │
                       │ odds_away      │
                       │ result         │
                       │ created_at     │
                       └────────────────┘

5.2 Relaciones

• Users 1:N Predictions - Un usuario puede tener multiples predicciones
• Events 1:N Predictions - Un evento puede tener multiples predicciones
• Users 1:N Alerts (futuro) - Un usuario puede tener multiples alertas

---

6. SEGURIDAD

6.1 Autenticacion

Mecanismo	Descripcion
JWT	Tokens de acceso firmados
Refresh Tokens	Renovacion de sesion
bcrypt	Hash de contrasenas
CORS	Configuracion de origenes

6.2 Autorizacion

Rol	Permisos
User	Lectura de datos propios, predicciones
Analyst	User + acceso a analytics avanzado
Admin	Acceso completo al sistema

6.3 Seguridad de Red

• HTTPS obligatorio en produccion
• Rate limiting en APIs
• Validacion de inputs
• Headers de seguridad (Helmet)

---

7. INFRAESTRUCTURA

7.1 Desarrollo Local

# docker-compose.yml (estructura)
services:
  backend:
    build: ./apps/backend
    ports:
      - "3090:3090"
    depends_on:
      - postgres

  frontend:
    build: ./apps/frontend
    ports:
      - "80:80"

  ml-engine:
    build: ./apps/ml
    ports:
      - "3093:3093"

  postgres:
    image: postgres:15
    ports:
      - "5432:5432"

  traefik:
    image: traefik:v2.10
    ports:
      - "80:80"
      - "443:443"

7.2 Puertos Asignados

Servicio	Puerto	Descripcion
Frontend	80	Aplicacion web (Nginx)
Backend	3090	API NestJS
ML Engine	3093	API FastAPI
PostgreSQL	5432	Base de datos
Traefik	80/443	Load balancer

---

8. PATRONES APLICADOS

Backend

Patron	Uso
Repository	Abstraccion de acceso a datos
DTO	Transferencia de datos
Guard	Proteccion de rutas
Pipe	Validacion y transformacion
Interceptor	Logging, response mapping

Frontend

Patron	Uso
Component	UI modular
Hook	Logica reutilizable
Store	Estado global (Zustand)
Service	Comunicacion con API

---

9. ESCALABILIDAD

Horizontal

• Servicios sin estado (stateless)
• Load balancing con Traefik
• Replicas de servicios
• Base de datos con replicas (futuro)

Vertical

• Optimizacion de queries
• Caching (Redis - futuro)
• Indices de base de datos
• Compresion de respuestas

---

10. OBSERVABILIDAD (Futuro)

Logging

• Formato estructurado (JSON)
• Correlacion de requests
• Niveles: ERROR, WARN, INFO, DEBUG

Metricas

• Prometheus endpoints
• Metricas de negocio
• Alertas automaticas

Trazas

• Distributed tracing
• Request correlation

---

11. REFERENCIAS

• Vision: VISION-PRODUCTO.md
• Stack: STACK-TECNOLOGICO.md
• ADR-001: ../97-adr/ADR-001-stack-tecnologico.md
• Service Descriptor: apps/backend/service.descriptor.yml

---

Documento: Arquitectura General Proyecto: Betting Analytics Version: 1.0.0 Fecha: 2026-01-04 Estado: Draft