---
id: "ARCH-BA"
title: "Arquitectura General - Betting Analytics"
type: "Architecture"
status: "Draft"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "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

```yaml
# 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](./VISION-PRODUCTO.md)
- **Stack:** [STACK-TECNOLOGICO.md](./STACK-TECNOLOGICO.md)
- **ADR-001:** [../97-adr/ADR-001-stack-tecnologico.md](../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