rckrdmrd/betting-analytics
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
betting-analytics/docs/00-vision-general/ARQUITECTURA-GENERAL.md
rckrdmrd 094493625c feat: Documentation and orchestration updates 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 05:35:34 -06:00

371 lines
12 KiB
Markdown
Raw Permalink Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink