rckrdmrd/betting-analytics
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Documentation and orchestration updates

Browse Source 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
rckrdmrd 2026-01-07 05:35:34 -06:00
parent 302b0b21e9
commit 094493625c
29 changed files with 4845 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

292
AGENTS.md Normal file
View File

@ -0,0 +1,292 @@
---
id: "AGENTS-BA"
title: "Guia para Agentes IA - Betting Analytics"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# AGENTS.md - Betting Analytics
Guia de trabajo para agentes de IA en el proyecto Betting Analytics.
---
## 1. INFORMACION DEL PROYECTO
| Campo | Valor |
|-------|-------|
| **Nombre** | Betting Analytics |
| **Prefijo** | BA |
| **Estado** | Planificacion |
| **Stack Backend** | NestJS + TypeORM + PostgreSQL |
| **Stack Frontend** | React + Vite + TypeScript |
| **Stack ML** | Python + FastAPI |
| **Repositorio** | betting-analytics |
---
## 2. UBICACIONES CLAVE
### Codigo Fuente
```
apps/
├── backend/ # API NestJS (Puerto 3090)
│ └── src/
│ ├── modules/ # Modulos de negocio
│ ├── config/ # Configuracion
│ └── shared/ # Tipos compartidos
├── frontend/ # Aplicacion React (Puerto 80)
└── ml/ # Servicio ML Python (Puerto 3093)
```
### Documentacion
```
docs/
├── 00-vision-general/ # Vision y arquitectura
├── 01-fase-alcance-inicial/ # EPICs MVP
│ └── BA-001-fundamentos/ # EPIC fundamentos
├── 04-fase-backlog/ # DoR, DoD, backlog
├── 90-transversal/ # Inventarios, arquitectura
├── 95-guias-desarrollo/ # Guias dev
├── 96-quick-reference/ # Cheatsheets
├── 97-adr/ # ADRs
├── planning/ # Board, config, tasks
└── archivados/ # Historicos
```
### Orchestration
```
orchestration/
├── agents/ # Configuracion de agentes
├── contexto/ # Contexto del proyecto
├── directivas/ # Directivas especificas
└── templates/ # Templates del proyecto
```
---
## 3. NOMENCLATURA
### Prefijos por Tipo
| Tipo | Prefijo | Ejemplo |
|------|---------|---------|
| EPIC | BA-NNN | BA-001-fundamentos |
| Requerimiento | RF-BA-NNN | RF-BA-001 |
| Especificacion | ET-BA-NNN | ET-BA-001 |
| Historia Usuario | US-BA-NNN | US-BA-001 |
| Tarea | TASK-BA-NNN | TASK-BA-001 |
| Bug | BUG-BA-NNN | BUG-BA-001 |
| ADR | ADR-NNN | ADR-001 |
### Modulos Identificados
| Modulo | Sufijo | Descripcion |
|--------|--------|-------------|
| AUTH | AUTH | Autenticacion y autorizacion |
| DATA | DATA | Ingestion de datos |
| ANALYTICS | AN | Analisis estadistico |
| PREDICTIONS | PRED | Modelos predictivos ML |
| REPORTING | REP | Reportes y visualizaciones |
---
## 4. FLUJO DE TRABAJO
### Tomar una Tarea
1. Revisar `docs/planning/Board.md` - columna "Por Hacer"
2. Leer archivo TASK correspondiente en `docs/planning/tasks/`
3. Actualizar YAML front-matter:
```yaml
status: "In Progress"
assignee: "@NombreAgente"
```
4. Commit: `Start TASK-BA-XXX: [descripcion]`
### Completar una Tarea
1. Verificar criterios de aceptacion cumplidos
2. Actualizar YAML front-matter:
```yaml
status: "Done"
completed_date: "YYYY-MM-DD"
actual_hours: X
```
3. Mover tarea en Board.md a "Hecho"
4. Commit: `Complete TASK-BA-XXX: [descripcion]`
### Reportar un Bug
1. Crear archivo en `docs/planning/bugs/BUG-BA-XXX.md`
2. Incluir YAML front-matter completo
3. Agregar a Board.md en seccion de bugs
4. Commit: `Report BUG-BA-XXX: [descripcion]`
---
## 5. FORMATO YAML REQUERIDO
### Historia de Usuario
```yaml
---
id: "US-BA-001"
title: "Titulo descriptivo"
type: "User Story"
status: "To Do"
priority: "Alta"
epic: "BA-001"
story_points: 5
labels: ["modulo", "feature"]
created_date: "YYYY-MM-DD"
updated_date: "YYYY-MM-DD"
---
```
### Tarea
```yaml
---
id: "TASK-BA-001"
title: "Descripcion tarea"
type: "Task"
status: "To Do"
priority: "P1"
parent_us: "US-BA-001"
estimated_hours: 4
assignee: ""
created_date: "YYYY-MM-DD"
---
```
### Bug
```yaml
---
id: "BUG-BA-001"
title: "Descripcion bug"
type: "Bug"
status: "Open"
severity: "P1"
priority: "Alta"
affected_module: "Backend"
steps_to_reproduce:
- "Paso 1"
- "Paso 2"
expected_behavior: "..."
actual_behavior: "..."
created_date: "YYYY-MM-DD"
---
```
---
## 6. ESTADOS VALIDOS
### User Stories
| Estado | Descripcion |
|--------|-------------|
| Backlog | No planificada |
| To Do | Planificada para sprint |
| In Progress | En desarrollo |
| In Review | En revision |
| Done | Completada |
### Tasks
| Estado | Descripcion |
|--------|-------------|
| To Do | Pendiente |
| In Progress | En desarrollo |
| Blocked | Bloqueada |
| Done | Completada |
### Bugs
| Estado | Descripcion |
|--------|-------------|
| Open | Reportado |
| In Progress | En investigacion |
| Fixed | Corregido |
| Done | Verificado |
| Won't Fix | No se corregira |
---
## 7. CONVENCIONES DE CODIGO
### Backend (NestJS)
- Modulos en `src/modules/{nombre}/`
- Entidades con decorador `@Entity()`
- DTOs con decoradores class-validator
- Servicios inyectables con `@Injectable()`
### Frontend (React)
- Componentes en PascalCase
- Hooks con prefijo `use`
- Estado global con Zustand (pendiente)
### Base de Datos
- Tablas en snake_case
- PKs: `id` tipo UUID
- Timestamps: `created_at`, `updated_at`
- Soft delete: `deleted_at`
---
## 8. COMANDOS UTILES
### Backend
```bash
cd apps/backend
npm run start:dev # Desarrollo
npm run build # Build produccion
npm run test # Tests unitarios
npm run lint # Linter
```
### Docker
```bash
docker-compose up -d # Levantar servicios
docker-compose logs -f # Ver logs
docker-compose down # Detener servicios
```
---
## 9. REFERENCIAS
- **Documentacion:** `docs/README.md`
- **Mapa Navegacion:** `docs/_MAP.md`
- **Board Activo:** `docs/planning/Board.md`
- **Configuracion:** `docs/planning/config.yml`
- **ADRs:** `docs/97-adr/`
---
## 10. CONTACTO
| Rol | Responsable |
|-----|-------------|
| **Product Owner** | @PO-Agent |
| **Backend Lead** | @Backend-Agent |
| **Frontend Lead** | @Frontend-Agent |
| **ML Lead** | @ML-Agent |
---
**Generado:** 2026-01-04
**Sistema:** NEXUS v3.4 + SIMCO + SCRUM
**Uso:** Guia de trabajo para agentes IA

370
docs/00-vision-general/ARQUITECTURA-GENERAL.md Normal file
View File

@ -0,0 +1,370 @@
---
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

401
docs/00-vision-general/STACK-TECNOLOGICO.md Normal file
View File

@ -0,0 +1,401 @@
---
id: "STACK-BA"
title: "Stack Tecnologico - Betting Analytics"
type: "Technical"
status: "Draft"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# Stack Tecnologico - Betting Analytics
---
## 1. RESUMEN DEL STACK
| Capa | Tecnologia | Version | Estado |
|------|------------|---------|--------|
| **Backend** | NestJS | ^10.3.0 | Implementado |
| **Frontend** | React + Vite | TBD | Planificado |
| **ML Engine** | FastAPI | TBD | Planificado |
| **Database** | PostgreSQL | 15+ | Planificado |
| **ORM** | TypeORM | ^0.3.19 | Implementado |
| **Autenticacion** | JWT + Passport | ^10.2.0 | Placeholder |
| **Containerizacion** | Docker | 24+ | Implementado |
---
## 2. BACKEND
### 2.1 Framework Principal
| Componente | Tecnologia | Version | Proposito |
|------------|------------|---------|-----------|
| **Framework** | NestJS | ^10.3.0 | Framework modular para Node.js |
| **Runtime** | Node.js | 20 LTS | Entorno de ejecucion |
| **Lenguaje** | TypeScript | ^5.3.3 | Tipado estatico |
### 2.2 Dependencias de Produccion
```json
{
"@nestjs/common": "^10.3.0",
"@nestjs/config": "^3.1.1",
"@nestjs/core": "^10.3.0",
"@nestjs/jwt": "^10.2.0",
"@nestjs/passport": "^10.0.3",
"@nestjs/platform-express": "^10.3.0",
"@nestjs/typeorm": "^10.0.1",
"bcrypt": "^5.1.1",
"class-transformer": "^0.5.1",
"class-validator": "^0.14.1",
"passport": "^0.7.0",
"passport-jwt": "^4.0.1",
"passport-local": "^1.0.0",
"pg": "^8.11.3",
"reflect-metadata": "^0.2.1",
"rxjs": "^7.8.1",
"typeorm": "^0.3.19",
"stripe": "^14.0.0"
}
```
### 2.3 Dependencias de Desarrollo
```json
{
"@nestjs/cli": "^10.3.0",
"@nestjs/testing": "^10.3.0",
"@types/bcrypt": "^5.0.2",
"@types/express": "^4.17.21",
"@types/jest": "^29.5.11",
"@types/node": "^20.10.6",
"@typescript-eslint/eslint-plugin": "^6.18.0",
"eslint": "^8.56.0",
"jest": "^29.7.0",
"prettier": "^3.1.1",
"supertest": "^6.3.4",
"ts-jest": "^29.1.1",
"typescript": "^5.3.3"
}
```
### 2.4 Configuracion
| Archivo | Proposito |
|---------|-----------|
| `tsconfig.json` | Configuracion TypeScript |
| `package.json` | Dependencias y scripts |
| `src/config/index.ts` | Configuracion de app, DB, JWT |
### 2.5 Scripts Disponibles
```bash
npm run start:dev # Desarrollo con hot-reload
npm run build # Build de produccion
npm run start:prod # Ejecutar build de produccion
npm run test # Tests unitarios
npm run test:e2e # Tests end-to-end
npm run lint # ESLint
npm run format # Prettier
```
---
## 3. FRONTEND (Planificado)
### 3.1 Stack Objetivo
| Componente | Tecnologia | Version | Proposito |
|------------|------------|---------|-----------|
| **Framework** | React | 18+ | UI Library |
| **Bundler** | Vite | 5+ | Build tool rapido |
| **Lenguaje** | TypeScript | 5+ | Tipado estatico |
| **Estado** | Zustand | TBD | Gestion de estado |
| **UI Kit** | TBD | - | Componentes UI |
| **HTTP** | Axios / Fetch | - | Cliente HTTP |
### 3.2 Estructura Planificada
```
frontend/
├── src/
│ ├── assets/ # Imagenes, fuentes
│ ├── components/ # Componentes reutilizables
│ │ ├── common/ # Botones, inputs, etc
│ │ ├── layout/ # Header, footer, sidebar
│ │ └── charts/ # Graficos y visualizaciones
│ ├── pages/ # Paginas/rutas
│ │ ├── auth/ # Login, registro
│ │ ├── dashboard/ # Dashboard principal
│ │ └── analytics/ # Vistas de analytics
│ ├── hooks/ # Custom hooks
│ ├── stores/ # Estado global (Zustand)
│ ├── services/ # Clientes API
│ ├── types/ # Definiciones TypeScript
│ ├── utils/ # Utilidades
│ ├── App.tsx # Componente principal
│ └── main.tsx # Punto de entrada
├── public/
├── index.html
├── vite.config.ts
├── tsconfig.json
└── package.json
```
---
## 4. ML ENGINE (Planificado)
### 4.1 Stack Objetivo
| Componente | Tecnologia | Version | Proposito |
|------------|------------|---------|-----------|
| **Framework** | FastAPI | TBD | API asincrona |
| **Runtime** | Python | 3.11 | Lenguaje |
| **ML** | scikit-learn | TBD | Modelos ML |
| **Data** | pandas | TBD | Manipulacion de datos |
| **Server** | Uvicorn | TBD | ASGI server |
### 4.2 Estructura Planificada
```
ml/
├── src/
│ ├── api/ # Endpoints FastAPI
│ │ ├── routes/ # Rutas
│ │ └── schemas/ # Pydantic schemas
│ ├── models/ # Modelos ML
│ │ ├── prediction/ # Modelos de prediccion
│ │ └── training/ # Scripts de entrenamiento
│ ├── pipelines/ # Pipelines de datos
│ ├── config/ # Configuracion
│ └── main.py # Punto de entrada
├── tests/
├── requirements.txt
├── requirements-dev.txt
└── Dockerfile
```
---
## 5. BASE DE DATOS
### 5.1 PostgreSQL
| Caracteristica | Valor |
|----------------|-------|
| **Version** | 15+ |
| **Puerto** | 5432 |
| **Base de datos** | betting_analytics |
| **Encoding** | UTF-8 |
### 5.2 Configuracion TypeORM
```typescript
// src/config/index.ts
export const databaseConfig = registerAs('database', () => ({
type: 'postgres',
host: process.env.DB_HOST || 'localhost',
port: parseInt(process.env.DB_PORT, 10) || 5432,
username: process.env.DB_USERNAME || 'postgres',
password: process.env.DB_PASSWORD || 'postgres',
database: process.env.DB_NAME || 'betting_analytics',
synchronize: process.env.NODE_ENV !== 'production',
logging: process.env.NODE_ENV === 'development',
}));
```
### 5.3 Migraciones
- TypeORM migrations para control de esquema
- No usar `synchronize: true` en produccion
- Versionado de migraciones en repositorio
---
## 6. AUTENTICACION
### 6.1 Stack de Autenticacion
| Componente | Tecnologia | Proposito |
|------------|------------|-----------|
| **Tokens** | JWT | Access tokens |
| **Estrategias** | Passport.js | Autenticacion modular |
| **Hash** | bcrypt | Hash de passwords |
### 6.2 Configuracion JWT
```typescript
// src/config/index.ts
export const jwtConfig = registerAs('jwt', () => ({
secret: process.env.JWT_SECRET || 'change-me-in-production',
expiresIn: process.env.JWT_EXPIRES_IN || '1d',
}));
```
### 6.3 Estrategias Planificadas
- `JwtStrategy` - Validacion de tokens
- `LocalStrategy` - Login con email/password
- `RefreshStrategy` - Renovacion de tokens
---
## 7. CONTAINERIZACION
### 7.1 Docker
| Servicio | Base Image | Puerto |
|----------|------------|--------|
| Backend | node:20-alpine | 3090 |
| Frontend | nginx:alpine | 80 |
| ML Engine | python:3.11-slim | 3093 |
| Database | postgres:15 | 5432 |
### 7.2 Dockerfile Backend
```dockerfile
# Multi-stage build
FROM node:20-alpine AS deps
FROM node:20-alpine AS builder
FROM node:20-alpine AS runner
# Non-root user
USER express
EXPOSE 3090
CMD ["node", "dist/main.js"]
```
### 7.3 Dockerfile Frontend
```dockerfile
# Multi-stage build
FROM node:20-alpine AS deps
FROM node:20-alpine AS builder
FROM nginx:alpine AS runner
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
---
## 8. HERRAMIENTAS DE DESARROLLO
### 8.1 Linting y Formato
| Herramienta | Proposito |
|-------------|-----------|
| ESLint | Linting de codigo |
| Prettier | Formato de codigo |
| TypeScript | Chequeo de tipos |
### 8.2 Testing
| Herramienta | Proposito |
|-------------|-----------|
| Jest | Tests unitarios |
| Supertest | Tests de integracion |
| ts-jest | Jest con TypeScript |
### 8.3 IDE Recomendado
- VS Code con extensiones:
- ESLint
- Prettier
- TypeScript
- NestJS Snippets
- Docker
---
## 9. VARIABLES DE ENTORNO
### Backend
```env
# App
NODE_ENV=development
PORT=3090
API_PREFIX=api
CORS_ORIGIN=*
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_NAME=betting_analytics
# JWT
JWT_SECRET=change-me-in-production
JWT_EXPIRES_IN=1d
```
### Frontend
```env
VITE_API_URL=http://localhost:3090/api
VITE_WS_URL=ws://localhost:3090
```
### ML Engine
```env
PYTHONDONTWRITEBYTECODE=1
PYTHONUNBUFFERED=1
PORT=3093
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/betting_analytics
```
---
## 10. DECISIONES TECNICAS
| Decision | Razon | ADR |
|----------|-------|-----|
| NestJS sobre Express | Arquitectura modular, TypeScript nativo | ADR-001 |
| TypeORM sobre Prisma | Decorators, integracion NestJS | ADR-001 |
| PostgreSQL | Datos relacionales, extensiones JSON | ADR-001 |
| JWT sobre Sessions | Stateless, escalabilidad | ADR-001 |
| Docker | Portabilidad, consistencia | ADR-001 |
---
## 11. ROADMAP TECNICO
### Fase 1 (Actual)
- [x] Estructura NestJS base
- [x] Configuracion TypeORM
- [x] Modulo auth placeholder
- [ ] Implementar autenticacion JWT
### Fase 2
- [ ] Setup frontend React + Vite
- [ ] Integracion con backend
- [ ] Dashboard basico
### Fase 3
- [ ] Setup ML Engine Python
- [ ] Modelos predictivos basicos
- [ ] API de predicciones
---
## 12. REFERENCIAS
- **Vision:** [VISION-PRODUCTO.md](./VISION-PRODUCTO.md)
- **Arquitectura:** [ARQUITECTURA-GENERAL.md](./ARQUITECTURA-GENERAL.md)
- **ADR-001:** [../97-adr/ADR-001-stack-tecnologico.md](../97-adr/ADR-001-stack-tecnologico.md)
- **NestJS Docs:** https://docs.nestjs.com
- **TypeORM Docs:** https://typeorm.io
---
**Documento:** Stack Tecnologico
**Proyecto:** Betting Analytics
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Draft

322
docs/00-vision-general/VISION-PRODUCTO.md Normal file
View File

@ -0,0 +1,322 @@
---
id: "VISION-BA"
title: "Vision del Producto - Betting Analytics"
type: "Vision"
status: "Draft"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# Vision del Producto - Betting Analytics
---
## 1. RESUMEN EJECUTIVO
**Betting Analytics** es una plataforma de analisis de apuestas deportivas que combina ingestion de datos en tiempo real, analisis estadistico avanzado y modelos predictivos de Machine Learning para proporcionar insights accionables a los usuarios.
---
## 2. PROBLEMA A RESOLVER
### Contexto del Mercado
El mercado de apuestas deportivas genera enormes cantidades de datos que, sin las herramientas adecuadas, son dificiles de analizar y aprovechar. Los apostadores enfrentan:
- **Sobrecarga de informacion:** Demasiados datos sin estructura
- **Falta de herramientas:** Analisis manual y propenso a errores
- **Decisiones emocionales:** Sin base estadistica solida
- **Fragmentacion:** Datos dispersos en multiples fuentes
### Oportunidad
Una plataforma que centralice, analice y prediga resultados puede proporcionar una ventaja competitiva significativa en el mercado de apuestas deportivas.
---
## 3. VISION DEL PRODUCTO
> **"Transformar datos de apuestas deportivas en decisiones inteligentes mediante analytics avanzado y predicciones basadas en Machine Learning."**
### Propuesta de Valor
| Para | Que necesitan | Nuestro producto | A diferencia de |
|------|---------------|------------------|-----------------|
| Apostadores profesionales | Decisiones basadas en datos | Plataforma de analytics y predicciones | Analisis manual |
| Analistas deportivos | Herramientas de analisis | Dashboard con metricas avanzadas | Hojas de calculo |
| Equipos de datos | Acceso a datos estructurados | APIs y pipelines de datos | Scraping manual |
---
## 4. OBJETIVOS ESTRATEGICOS
### Corto Plazo (MVP - 3 meses)
1. **Ingestion de Datos**
- Conectores para principales fuentes de datos
- Pipeline de procesamiento en tiempo real
- Almacenamiento estructurado
2. **Analytics Basico**
- Dashboard con metricas clave
- Historico de rendimiento
- Comparativas estadisticas
3. **Autenticacion**
- Sistema de usuarios
- Roles y permisos
- Seguridad JWT
### Mediano Plazo (6 meses)
4. **Modelos Predictivos**
- Modelos ML para predicciones
- Backtesting de estrategias
- Alertas inteligentes
5. **Reportes Avanzados**
- Reportes personalizados
- Exportacion de datos
- Integraciones API
### Largo Plazo (12 meses)
6. **Plataforma Escalable**
- Multi-tenancy
- APIs publicas
- Marketplace de modelos
---
## 5. USUARIOS OBJETIVO
### Persona Principal: El Apostador Profesional
| Atributo | Descripcion |
|----------|-------------|
| **Nombre** | Carlos - El Analista |
| **Edad** | 28-45 anos |
| **Ocupacion** | Apostador profesional / Semi-profesional |
| **Objetivo** | Maximizar ROI en apuestas deportivas |
| **Frustracion** | Falta de herramientas profesionales |
| **Necesidad** | Datos estructurados y predicciones confiables |
### Persona Secundaria: El Analista de Datos
| Atributo | Descripcion |
|----------|-------------|
| **Nombre** | Maria - La Data Scientist |
| **Edad** | 25-35 anos |
| **Ocupacion** | Analista de datos / ML Engineer |
| **Objetivo** | Desarrollar y probar modelos predictivos |
| **Frustracion** | Dificultad para obtener datos limpios |
| **Necesidad** | APIs de datos y herramientas de analisis |
---
## 6. FUNCIONALIDADES PRINCIPALES
### 6.1 Ingestion de Datos (BA-002)
- Conectores para APIs de datos deportivos
- Scraping automatizado de cuotas
- Procesamiento en tiempo real
- Historico de datos
### 6.2 Analytics Engine (BA-003)
- Dashboard interactivo
- Metricas de rendimiento
- Analisis comparativo
- Tendencias y patrones
### 6.3 Predicciones ML (BA-004)
- Modelos de clasificacion
- Prediccion de resultados
- Estimacion de probabilidades
- Backtesting
### 6.4 Reportes (BA-005)
- Generacion de reportes
- Visualizaciones avanzadas
- Exportacion (PDF, Excel)
- Notificaciones
---
## 7. METRICAS DE EXITO
### KPIs de Producto
| Metrica | Target MVP | Target 6M |
|---------|------------|-----------|
| Precision de predicciones | 55% | 60% |
| Tiempo de procesamiento | <5s | <2s |
| Uptime del sistema | 99% | 99.9% |
| Latencia API | <200ms | <100ms |
### KPIs de Negocio
| Metrica | Target MVP | Target 6M |
|---------|------------|-----------|
| Usuarios activos | 100 | 1,000 |
| Retencion mensual | 40% | 60% |
| NPS | 30 | 50 |
---
## 8. RESTRICCIONES Y CONSIDERACIONES
### Restricciones Tecnicas
- **Infraestructura:** Docker-based, escalable horizontalmente
- **Base de datos:** PostgreSQL para datos transaccionales
- **Real-time:** Latencia maxima de 5 segundos
- **Seguridad:** Encriptacion en transito y reposo
### Restricciones Legales
- Cumplimiento con regulaciones de apuestas por jurisdiccion
- Proteccion de datos personales (GDPR-like)
- Terminos de uso de APIs de terceros
### Restricciones de Recursos
- Equipo inicial: 3-5 agentes IA
- Timeline MVP: 3 meses
- Presupuesto: TBD
---
## 9. ROADMAP ALTO NIVEL
```
Q1 2026
├── Mes 1: Fundamentos (BA-001)
│ ├── Estructura del proyecto
│ ├── Autenticacion JWT
│ └── API base
├── Mes 2: Ingestion (BA-002)
│ ├── Conectores de datos
│ ├── Pipeline de procesamiento
│ └── Almacenamiento
└── Mes 3: Analytics (BA-003)
├── Dashboard basico
├── Metricas clave
└── MVP Release
Q2 2026
├── Mes 4-5: ML Engine (BA-004)
│ ├── Modelos predictivos
│ ├── Backtesting
│ └── API de predicciones
└── Mes 6: Reportes (BA-005)
├── Generador de reportes
├── Visualizaciones
└── v1.0 Release
```
---
## 10. MODELO SAAS
### 10.1 Arquitectura Multi-tenant
Betting Analytics opera como plataforma SaaS con aislamiento de datos por tenant mediante Row-Level Security (RLS) en PostgreSQL.
```yaml
Tipo: Single Database, Shared Schema
Aislamiento: RLS por tenant_id
Branding: Configurable por tenant
```
### 10.2 Planes de Suscripcion
| Plan | Precio | Predicciones/mes | Modelos ML | Historico | Usuarios | Soporte |
|------|--------|------------------|------------|-----------|----------|---------|
| Free | $0 | 50 | 1 basico | 30 dias | 1 | Comunidad |
| Pro | $39/mes | 500 | 3 avanzados | 1 ano | 5 | Email |
| Enterprise | $149/mes | Ilimitado | Custom | Ilimitado | Ilimitado | Dedicado |
### 10.3 Integracion Stripe
```yaml
Productos Stripe:
ba_pro_monthly:
precio: $39/mes
type: subscription
ba_enterprise_monthly:
precio: $149/mes
type: subscription
ba_predictions_100:
precio: $9
type: one_time
descripcion: "100 predicciones adicionales"
Webhooks:
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.payment_succeeded
- invoice.payment_failed
- checkout.session.completed
```
### 10.4 Estructura de Portales
```yaml
Portal 1 - Usuario (Analyst):
URL: app.{tenant}.betting-analytics.com
Funciones:
- Dashboard de predicciones
- Acceso a modelos segun plan
- Historial personal
- Perfil y configuracion
Portal 2 - Admin Cliente (Tenant Admin):
URL: admin.{tenant}.betting-analytics.com
Funciones:
- Gestion de usuarios
- Configuracion del tenant
- Facturacion y suscripcion
- Reportes de uso
Portal 3 - Admin SaaS (Super Admin):
URL: admin.betting-analytics.com
Funciones:
- Gestion de todos los tenants
- Configuracion de planes
- Monitoreo del sistema
- Analytics globales
```
### 10.5 Modulos SaaS
| ID | Modulo | Descripcion | Documento |
|----|--------|-------------|-----------|
| BA-007 | Tenants | Multi-tenancy con RLS | [BA-007-TENANTS](../02-definicion-modulos/BA-007-TENANTS.md) |
| BA-008 | Payments | Integracion Stripe | [BA-008-PAYMENTS](../02-definicion-modulos/BA-008-PAYMENTS.md) |
| BA-009 | Portals | 3 portales diferenciados | [BA-009-PORTALS](../02-definicion-modulos/BA-009-PORTALS.md) |
---
## 11. REFERENCIAS
- **Arquitectura:** [ARQUITECTURA-GENERAL.md](./ARQUITECTURA-GENERAL.md)
- **Stack:** [STACK-TECNOLOGICO.md](./STACK-TECNOLOGICO.md)
- **Modulos SaaS:** [../02-definicion-modulos/](../02-definicion-modulos/)
- **ADRs:** [../97-adr/](../97-adr/)
- **Board:** [../planning/Board.md](../planning/Board.md)
---
**Documento:** Vision del Producto
**Proyecto:** Betting Analytics
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Draft

52
docs/00-vision-general/_MAP.md Normal file
View File

@ -0,0 +1,52 @@
---
id: "MAP-00-VISION"
title: "Mapa de Navegacion - Vision General"
type: "Navigation"
folder: "00-vision-general"
updated_date: "2026-01-04"
---
# _MAP: 00-vision-general
**Carpeta:** Vision General del Proyecto
**Proyecto:** Betting Analytics
**Actualizado:** 2026-01-04
---
## Proposito
Esta carpeta contiene la documentacion de alto nivel que define la vision, arquitectura y stack tecnologico del proyecto Betting Analytics.
---
## Contenido
| Archivo | Titulo | Estado | Descripcion |
|---------|--------|--------|-------------|
| [VISION-PRODUCTO.md](./VISION-PRODUCTO.md) | Vision del Producto | Draft | Objetivos, usuarios, propuesta de valor |
| [ARQUITECTURA-GENERAL.md](./ARQUITECTURA-GENERAL.md) | Arquitectura General | Draft | Diseno de sistema, componentes, flujos |
| [STACK-TECNOLOGICO.md](./STACK-TECNOLOGICO.md) | Stack Tecnologico | Draft | Tecnologias, dependencias, configuracion |
---
## Estadisticas
| Metrica | Valor |
|---------|-------|
| Total documentos | 3 |
| Estado Draft | 3 |
| Estado Aprobado | 0 |
---
## Referencias
- **Nivel superior:** [../README.md](../README.md)
- **Mapa principal:** [../_MAP.md](../_MAP.md)
- **ADRs:** [../97-adr/](../97-adr/)
---
**Generado:** 2026-01-04
**Mantenedor:** @Doc-Agent

146
docs/01-fase-alcance-inicial/BA-001-fundamentos/README.md Normal file
View File

@ -0,0 +1,146 @@
---
id: "EPIC-BA-001"
title: "EPIC BA-001: Fundamentos"
type: "EPIC"
status: "Planned"
phase: "01-fase-alcance-inicial"
story_points: 0
budget: "TBD"
sprint: "Sprint-1"
labels: ["fundamentos", "auth", "api", "mvp"]
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# EPIC BA-001: Fundamentos
**Fase:** 01 - Alcance Inicial
**Estado:** Planned
**Sprint:** Sprint-1 (planificado)
---
## Descripcion
Esta EPIC establece los fundamentos tecnicos del proyecto Betting Analytics, incluyendo:
- Configuracion inicial del backend NestJS
- Sistema de autenticacion con JWT
- API base con validaciones
- Estructura de base de datos inicial
- Configuracion de Docker para desarrollo
---
## Objetivos
1. **Autenticacion completa** - Login, registro, refresh tokens
2. **API REST funcional** - Endpoints base con validacion
3. **Base de datos** - Esquema inicial con TypeORM
4. **Docker** - Ambiente de desarrollo containerizado
5. **Documentacion** - API documentada con Swagger
---
## Alcance
### Incluido
- Modulo de autenticacion (auth)
- Modulo de usuarios (users)
- Configuracion de base de datos
- Docker Compose para desarrollo
- Documentacion Swagger
### Excluido
- Modulos de negocio (data, analytics, predictions)
- Frontend
- ML Engine
- Deploy a produccion
---
## Requerimientos Funcionales
| ID | Titulo | Estado |
|----|--------|--------|
| RF-BA-001 | Sistema de autenticacion JWT | Pendiente |
| RF-BA-002 | Gestion de usuarios | Pendiente |
| RF-BA-003 | API REST base | Pendiente |
---
## User Stories
| ID | Titulo | SP | Estado |
|----|--------|-----|--------|
| US-BA-001 | Configurar autenticacion JWT | 8 | Backlog |
| US-BA-002 | Registro de usuarios | 5 | Backlog |
| US-BA-003 | Login de usuarios | 5 | Backlog |
| US-BA-004 | Refresh de tokens | 3 | Backlog |
| US-BA-005 | Estructura base de datos | 5 | Backlog |
**Total Story Points estimados:** 26 SP
---
## Metricas
| Metrica | Estimado | Real |
|---------|----------|------|
| Story Points | 26 | - |
| RF | 3 | 0 |
| US | 5 | 0 |
| Completion | 0% | - |
---
## Dependencias
### Entradas
- Ninguna (EPIC inicial)
### Salidas
- BA-002 (Ingestion) depende de autenticacion
- BA-003 (Analytics) depende de API base
---
## Estructura de Carpeta
```
BA-001-fundamentos/
├── README.md # Este archivo
├── _MAP.md # Mapa de navegacion
├── requerimientos/ # RFs
│ ├── _MAP.md
│ └── RF-BA-001.md
├── especificaciones/ # ETs
│ ├── _MAP.md
│ └── ET-BA-001.md
├── historias-usuario/ # US
│ ├── _MAP.md
│ └── US-BA-001.md
└── implementacion/ # Trazabilidad
├── TRACEABILITY.yml
├── DATABASE.yml
└── BACKEND.yml
```
---
## Referencias
- **Fase:** [../README.md](../README.md)
- **Vision:** [../../00-vision-general/VISION-PRODUCTO.md](../../00-vision-general/VISION-PRODUCTO.md)
- **Arquitectura:** [../../00-vision-general/ARQUITECTURA-GENERAL.md](../../00-vision-general/ARQUITECTURA-GENERAL.md)
- **Board:** [../../planning/Board.md](../../planning/Board.md)
---
**Creado:** 2026-01-04
**Actualizado:** 2026-01-04
**Responsable:** @Backend-Agent

90
docs/01-fase-alcance-inicial/BA-001-fundamentos/_MAP.md Normal file
View File

@ -0,0 +1,90 @@
---
id: "MAP-BA-001"
title: "Mapa de Navegacion - EPIC BA-001"
type: "Navigation"
epic: "BA-001"
folder: "BA-001-fundamentos"
phase: "01-fase-alcance-inicial"
updated_date: "2026-01-04"
---
# _MAP: BA-001 - Fundamentos
**Epica:** BA-001
**Nombre:** Fundamentos
**Fase:** 01 - Alcance Inicial
**Story Points:** 26 SP (estimado)
**Estado:** Planned
**Sprint:** Sprint-1
---
## Proposito
Establecer los fundamentos tecnicos del proyecto: autenticacion, API base, estructura de base de datos y ambiente de desarrollo containerizado.
---
## Contenido
### Requerimientos Funcionales (0)
| ID | Archivo | Titulo | Estado |
|----|---------|--------|--------|
| - | - | Pendiente de crear | - |
### Especificaciones Tecnicas (0)
| ID | Archivo | Titulo | RF | Estado |
|----|---------|--------|-----|--------|
| - | - | Pendiente de crear | - | - |
### Historias de Usuario (0)
| ID | Archivo | Titulo | SP | Estado |
|----|---------|--------|----|--------|
| - | - | Pendiente de crear | - | - |
**Total Story Points:** 0 SP (documentados)
### Implementacion
- Pendiente de crear trazabilidad
---
## Estructura
```
BA-001-fundamentos/
├── README.md # Descripcion de la EPIC
├── _MAP.md # Este archivo
├── requerimientos/ # Pendiente
├── especificaciones/ # Pendiente
├── historias-usuario/ # Pendiente
└── implementacion/ # Pendiente
```
---
## Referencias
- **README:** [README.md](./README.md)
- **Fase:** [../README.md](../README.md)
- **Docs:** [../../README.md](../../README.md)
---
## Metricas
| Metrica | Valor |
|---------|-------|
| RF documentados | 0 |
| ET documentados | 0 |
| US documentadas | 0 |
| Completion | 0% |
---
**Generado:** 2026-01-04
**Mantenedor:** @Backend-Agent

53
docs/01-fase-alcance-inicial/_MAP.md Normal file
View File

@ -0,0 +1,53 @@
---
id: "MAP-01-ALCANCE"
title: "Mapa de Navegacion - Fase Alcance Inicial"
type: "Navigation"
folder: "01-fase-alcance-inicial"
updated_date: "2026-01-04"
---
# _MAP: 01-fase-alcance-inicial
**Carpeta:** Fase 01 - Alcance Inicial
**Proyecto:** Betting Analytics
**Actualizado:** 2026-01-04
---
## Proposito
Esta fase contiene las EPICs fundamentales para el MVP del proyecto, incluyendo los fundamentos tecnicos, ingestion de datos y motor de analytics basico.
---
## EPICs de la Fase
| ID | Nombre | Descripcion | SP | Estado |
|----|--------|-------------|-----|--------|
| [BA-001](./BA-001-fundamentos/) | Fundamentos | Auth, API, DB base | 26 | Planned |
| BA-002 | Ingestion de Datos | Conectores, pipelines | TBD | Backlog |
| BA-003 | Analytics Engine | Metricas, dashboard | TBD | Backlog |
---
## Estadisticas
| Metrica | Valor |
|---------|-------|
| Total EPICs | 3 |
| EPICs documentadas | 1 |
| SP totales estimados | 26+ |
| Progreso fase | 0% |
---
## Referencias
- **Nivel superior:** [../README.md](../README.md)
- **Mapa principal:** [../_MAP.md](../_MAP.md)
- **Vision:** [../00-vision-general/VISION-PRODUCTO.md](../00-vision-general/VISION-PRODUCTO.md)
---
**Generado:** 2026-01-04
**Mantenedor:** @Doc-Agent

218
docs/02-definicion-modulos/BA-007-TENANTS.md Normal file
View File

@ -0,0 +1,218 @@
---
id: "BA-007-TENANTS"
title: "BA-007: Modulo de Tenants"
type: "Module Definition"
epic: "BA-007"
status: "Draft"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# BA-007: Modulo de Tenants
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Definicion
**Prioridad:** Alta
---
## Descripcion General
El modulo de Tenants proporciona la arquitectura multi-tenant que permite aislar datos y configuraciones entre diferentes organizaciones que utilicen la plataforma de Betting Analytics como SaaS.
---
## Objetivos
1. Aislar completamente los datos entre tenants
2. Permitir configuracion personalizada por tenant
3. Gestionar limites y cuotas segun plan
4. Preparar arquitectura para comercializacion SaaS
---
## Entidades del Dominio
### Tenant
```yaml
Entidad: Tenant
Descripcion: Organizacion que utiliza la plataforma
Atributos:
- id: UUID (PK)
- name: string
- slug: string (unico, URL-friendly)
- status: enum [active, suspended, trial, cancelled]
- plan_id: UUID (FK a Plan)
- settings: JSONB
- limits: JSONB
- created_at: timestamp
- updated_at: timestamp
- deleted_at: timestamp (soft delete)
Relaciones:
- 1:N con User
- 1:N con Prediction
- 1:N con Model
- N:1 con Plan
```
### Plan
```yaml
Entidad: Plan
Descripcion: Plan de suscripcion con limites
Atributos:
- id: UUID (PK)
- name: string (Free, Pro, Enterprise)
- code: string
- features: JSONB
- limits: JSONB
- predictions_per_month: number
- models_max: number
- history_days: number
- users_max: number
- price_monthly: decimal
- price_yearly: decimal
- is_active: boolean
- created_at: timestamp
- updated_at: timestamp
Relaciones:
- 1:N con Tenant
```
---
## Funcionalidades
### F-007.1: Gestion de Tenants
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-007.1.1 | Crear tenant | Registro de nueva organizacion | Alta |
| F-007.1.2 | Editar tenant | Modificar datos y configuracion | Alta |
| F-007.1.3 | Suspender tenant | Desactivar acceso temporalmente | Media |
| F-007.1.4 | Eliminar tenant | Soft delete con retencion | Baja |
### F-007.2: Aislamiento de Datos
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-007.2.1 | RLS PostgreSQL | Row-Level Security por tenant_id | Alta |
| F-007.2.2 | Middleware | Inyeccion automatica de tenant_id | Alta |
| F-007.2.3 | Query scoping | Filtrado automatico en queries | Alta |
---
## Reglas de Negocio
```yaml
RN-007.1:
Descripcion: Todo tenant debe tener un plan asignado
Default: Plan "Free"
RN-007.2:
Descripcion: El slug del tenant debe ser unico
Validacion: Regex ^[a-z0-9-]+$
RN-007.3:
Descripcion: Tenant suspendido no permite login
Accion: Validar status en middleware
RN-007.4:
Descripcion: Soft delete conserva datos 90 dias
```
---
## API Endpoints
```yaml
Base: /api/v1/tenants
Endpoints:
POST /tenants:
Descripcion: Crear tenant (Super Admin)
Body: { name, slug, plan_id }
Response: 201 Created
GET /tenants:
Descripcion: Listar tenants (Super Admin)
Response: 200 OK (paginado)
GET /tenants/:id:
Descripcion: Obtener tenant por ID
Response: 200 OK
PUT /tenants/:id:
Descripcion: Actualizar tenant
Response: 200 OK
PATCH /tenants/:id/status:
Descripcion: Cambiar estado
Body: { status }
Response: 200 OK
GET /tenants/current:
Descripcion: Tenant del usuario actual
Response: 200 OK
```
---
## Consideraciones Tecnicas
### Estrategia Multi-Tenant
```yaml
Tipo: Single Database, Shared Schema
Aislamiento: Row-Level Security (RLS) PostgreSQL
Implementacion:
1. Columna tenant_id en tablas principales
2. Politicas RLS que filtran por tenant_id
3. Middleware que extrae tenant del JWT
4. SET app.current_tenant antes de queries
```
### Ejemplo RLS
```sql
CREATE POLICY tenant_isolation ON predictions
USING (tenant_id = current_setting('app.current_tenant')::uuid);
ALTER TABLE predictions ENABLE ROW LEVEL SECURITY;
```
---
## Dependencias
```yaml
Dependencias:
- BA-001 (auth): Autenticacion de usuarios
- BA-008 (payments): Gestion de planes/suscripciones
Catalogos:
- shared/catalog/multi-tenancy/
```
---
## Criterios de Aceptacion
- [ ] Tenant puede ser creado con datos minimos
- [ ] RLS impide acceso a datos de otros tenants
- [ ] Limites del plan se validan antes de operaciones
- [ ] Soft delete funciona correctamente
- [ ] API responde correctamente
---
**Documento generado por:** NEXUS Orchestration
**Fecha:** 2026-01-04

312
docs/02-definicion-modulos/BA-008-PAYMENTS.md Normal file
View File

@ -0,0 +1,312 @@
---
id: "BA-008-PAYMENTS"
title: "BA-008: Modulo de Payments"
type: "Module Definition"
epic: "BA-008"
status: "Draft"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# BA-008: Modulo de Payments
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Definicion
**Prioridad:** Alta
---
## Descripcion General
El modulo de Payments proporciona la integracion con Stripe para gestionar suscripciones, pagos y facturacion del sistema SaaS de Betting Analytics.
---
## Objetivos
1. Integrar Stripe como pasarela de pagos
2. Gestionar planes de suscripcion (Free, Pro, Enterprise)
3. Implementar checkout flow con Stripe Elements
4. Automatizar facturacion y cobros recurrentes
5. Gestionar creditos de prediccion por tenant
---
## Planes de Suscripcion
```yaml
Planes:
free:
nombre: "Free"
precio: $0/mes
limites:
predicciones_mes: 50
modelos_max: 1
historico_dias: 30
usuarios_max: 1
features:
- Predicciones basicas
- 1 modelo standard
- Soporte comunidad
pro:
nombre: "Pro"
precio: $39/mes
stripe_price_id: ba_pro_monthly
limites:
predicciones_mes: 500
modelos_max: 3
historico_dias: 365
usuarios_max: 5
features:
- Todo de Free
- Modelos avanzados
- API access
- Soporte email
enterprise:
nombre: "Enterprise"
precio: $149/mes
stripe_price_id: ba_enterprise_monthly
limites:
predicciones_mes: unlimited
modelos_max: unlimited
historico_dias: unlimited
usuarios_max: unlimited
features:
- Todo de Pro
- Modelos custom
- SLA garantizado
- Soporte dedicado
```
---
## Productos Stripe
```yaml
Productos:
ba_pro_monthly:
type: subscription
nombre: "Betting Analytics Pro"
precio: $39/mes
billing_interval: monthly
metadata:
plan_code: pro
predictions: 500
ba_enterprise_monthly:
type: subscription
nombre: "Betting Analytics Enterprise"
precio: $149/mes
billing_interval: monthly
metadata:
plan_code: enterprise
predictions: unlimited
ba_predictions_100:
type: one_time
nombre: "Pack 100 Predicciones"
precio: $9
metadata:
product_type: credits
credits_amount: 100
```
---
## Entidades del Dominio
### Subscription
```yaml
Entidad: Subscription
Descripcion: Suscripcion activa de un tenant
Atributos:
- id: UUID (PK)
- tenant_id: UUID (FK)
- plan_id: UUID (FK)
- stripe_subscription_id: string
- stripe_customer_id: string
- status: enum [active, past_due, canceled, incomplete, trialing]
- current_period_start: timestamp
- current_period_end: timestamp
- cancel_at_period_end: boolean
- created_at: timestamp
- updated_at: timestamp
Relaciones:
- N:1 con Tenant
- N:1 con Plan
- 1:N con Invoice
```
### Invoice
```yaml
Entidad: Invoice
Descripcion: Factura de Stripe
Atributos:
- id: UUID (PK)
- tenant_id: UUID (FK)
- subscription_id: UUID (FK)
- stripe_invoice_id: string
- amount_due: decimal
- amount_paid: decimal
- currency: string
- status: enum [draft, open, paid, void, uncollectible]
- invoice_pdf_url: string
- paid_at: timestamp
- created_at: timestamp
```
### PredictionCredit
```yaml
Entidad: PredictionCredit
Descripcion: Balance de creditos por tenant
Atributos:
- id: UUID (PK)
- tenant_id: UUID (FK, unico)
- credits_included: integer
- credits_remaining: integer
- credits_used: integer
- credits_extra: integer
- resets_at: timestamp
- created_at: timestamp
- updated_at: timestamp
Notas:
- credits_remaining se resetea cada periodo
- credits_extra no expiran
```
---
## Webhooks Stripe
```yaml
Eventos:
- customer.subscription.created:
accion: Crear Subscription en BD
- customer.subscription.updated:
accion: Actualizar status/periodo
- customer.subscription.deleted:
accion: Marcar como canceled
- invoice.payment_succeeded:
accion: Registrar pago, resetear creditos
- invoice.payment_failed:
accion: Marcar past_due, notificar
- checkout.session.completed:
accion: Activar plan o creditos
```
---
## Funcionalidades
### F-008.1: Gestion de Suscripciones
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-008.1.1 | Ver planes | Listar planes disponibles | Alta |
| F-008.1.2 | Suscribirse | Checkout con Stripe | Alta |
| F-008.1.3 | Cambiar plan | Upgrade/downgrade | Media |
| F-008.1.4 | Cancelar | Cancelar al final del periodo | Media |
### F-008.2: Facturacion
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-008.2.1 | Ver facturas | Historial de facturas | Alta |
| F-008.2.2 | Descargar PDF | Obtener factura PDF | Media |
| F-008.2.3 | Portal billing | Redirect a Stripe portal | Alta |
### F-008.3: Creditos
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-008.3.1 | Ver balance | Creditos restantes | Alta |
| F-008.3.2 | Comprar extra | Pack de creditos | Media |
| F-008.3.3 | Consumir | Decrementar al predecir | Alta |
---
## API Endpoints
```yaml
Base: /api/v1/billing
Endpoints:
GET /billing/plans:
Descripcion: Listar planes disponibles
Response: 200 OK
POST /billing/checkout:
Descripcion: Crear sesion de checkout
Body: { plan_code, success_url, cancel_url }
Response: 200 { checkout_url }
GET /billing/subscription:
Descripcion: Suscripcion actual del tenant
Response: 200 OK
POST /billing/subscription/cancel:
Descripcion: Cancelar al final del periodo
Response: 200 OK
GET /billing/invoices:
Descripcion: Historial de facturas
Response: 200 OK (paginado)
GET /billing/credits:
Descripcion: Balance de creditos
Response: 200 OK
POST /billing/credits/purchase:
Descripcion: Comprar creditos extra
Body: { pack_id }
Response: 200 { checkout_url }
POST /billing/webhook:
Descripcion: Webhook de Stripe
Headers: { stripe-signature }
Response: 200 OK
```
---
## Dependencias
```yaml
Dependencias:
- BA-007 (tenants): Multi-tenancy
- BA-001 (auth): Autenticacion
Servicios Externos:
- Stripe API
- Stripe Webhooks
Catalogos:
- shared/catalog/payments/
```
---
## Criterios de Aceptacion
- [ ] Usuario puede ver planes y precios
- [ ] Checkout redirect a Stripe funciona
- [ ] Webhooks actualizan estado correctamente
- [ ] Creditos se resetean cada periodo
- [ ] Portal de billing funciona
- [ ] Facturas se pueden descargar
---
**Documento generado por:** NEXUS Orchestration
**Fecha:** 2026-01-04

324
docs/02-definicion-modulos/BA-009-PORTALS.md Normal file
View File

@ -0,0 +1,324 @@
---
id: "BA-009-PORTALS"
title: "BA-009: Modulo de Portales"
type: "Module Definition"
epic: "BA-009"
status: "Draft"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# BA-009: Modulo de Portales
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Definicion
**Prioridad:** Alta
---
## Descripcion General
El modulo de Portales define la arquitectura de 3 interfaces diferenciadas segun el tipo de usuario: Usuario General (analista), Admin Cliente (tenant admin) y Admin SaaS (super admin).
---
## Objetivos
1. Proporcionar experiencia de usuario diferenciada por rol
2. Separar funcionalidades administrativas de uso general
3. Permitir gestion centralizada del SaaS
4. Facilitar escalabilidad del sistema
---
## Estructura de Portales
### Portal 1: Usuario General (Analyst)
```yaml
Portal: Usuario General
URL: app.{tenant}.betting-analytics.com
Roles: analyst, viewer
Dashboard:
- Resumen de predicciones recientes
- Creditos restantes
- Modelos disponibles
- Estadisticas personales
Modulos:
predicciones:
- Crear nueva prediccion
- Ver historial de predicciones
- Detalles de prediccion
- Exportar resultados
modelos:
- Explorar modelos disponibles
- Ver estadisticas de precision
- Favoritos
perfil:
- Datos personales
- Preferencias
- Notificaciones
- API keys (si plan lo permite)
Restricciones:
- Solo ve datos propios
- Limitado por creditos del plan
- Sin acceso a configuracion del tenant
```
### Portal 2: Admin Cliente (Tenant Admin)
```yaml
Portal: Admin Cliente
URL: admin.{tenant}.betting-analytics.com
Roles: tenant_admin
Dashboard:
- Metricas de uso del tenant
- Usuarios activos
- Creditos consumidos/restantes
- Alertas de limites
Modulos:
usuarios:
- Listar usuarios del tenant
- Invitar nuevos usuarios
- Editar roles
- Desactivar usuarios
organizacion:
- Datos del tenant
- Configuracion general
- Integraciones
- Webhooks
facturacion:
- Plan actual
- Cambiar plan
- Historial de facturas
- Metodos de pago
- Portal de Stripe
reportes:
- Uso por usuario
- Predicciones por periodo
- Consumo de creditos
- Exportar reportes
Restricciones:
- Solo ve datos de su tenant
- No puede modificar planes globales
- No ve otros tenants
```
### Portal 3: Admin SaaS (Super Admin)
```yaml
Portal: Admin SaaS
URL: admin.betting-analytics.com
Roles: super_admin
Dashboard:
- Tenants totales/activos
- MRR (Monthly Recurring Revenue)
- Usuarios totales
- Predicciones globales
- Health del sistema
Modulos:
tenants:
- Listar todos los tenants
- Crear tenant
- Editar tenant
- Suspender/reactivar
- Ver metricas por tenant
planes:
- Configurar planes
- Editar precios
- Activar/desactivar planes
- Configurar limites
usuarios_globales:
- Buscar usuarios globalmente
- Impersonar usuario
- Reset de password
- Ver actividad
sistema:
- Configuracion global
- Feature flags
- Mantenimiento
- Logs del sistema
soporte:
- Tickets abiertos
- Responder tickets
- Metricas de soporte
analytics:
- Metricas de negocio
- Conversion por plan
- Churn rate
- LTV por segmento
Restricciones:
- Acceso total al sistema
- Requiere 2FA obligatorio
- Auditoria de acciones
```
---
## Componentes Compartidos
```yaml
Componentes:
header:
- Logo
- Navegacion principal
- Notificaciones
- Menu usuario
sidebar:
- Navegacion contextual
- Estado del plan (si aplica)
- Accesos rapidos
footer:
- Links legales
- Version
- Soporte
auth:
- Login
- Registro (solo tenant nuevo)
- Forgot password
- 2FA setup
```
---
## Routing
```yaml
Rutas por Portal:
Usuario General:
/dashboard # Dashboard principal
/predictions # Listado de predicciones
/predictions/new # Nueva prediccion
/predictions/:id # Detalle
/models # Modelos disponibles
/models/:id # Detalle modelo
/profile # Perfil
/settings # Configuracion
Admin Cliente:
/dashboard # Dashboard tenant
/users # Gestion usuarios
/users/invite # Invitar usuario
/organization # Configuracion
/billing # Facturacion
/billing/plans # Cambiar plan
/billing/invoices # Facturas
/reports # Reportes
Admin SaaS:
/dashboard # Dashboard global
/tenants # Gestion tenants
/tenants/:id # Detalle tenant
/plans # Gestion planes
/users # Usuarios globales
/system # Configuracion
/support # Soporte
/analytics # Metricas
```
---
## Permisos por Portal
```yaml
Matriz de Permisos:
| Permiso | Usuario | Admin Cliente | Admin SaaS |
|---------|---------|---------------|------------|
| Ver predicciones propias | SI | SI | SI |
| Ver predicciones del tenant | NO | SI | SI |
| Crear predicciones | SI | SI | SI |
| Gestionar usuarios | NO | SI | SI |
| Ver facturacion | NO | SI | SI |
| Cambiar plan | NO | SI | SI |
| Ver todos los tenants | NO | NO | SI |
| Configurar planes | NO | NO | SI |
| Configurar sistema | NO | NO | SI |
```
---
## Funcionalidades
### F-009.1: Portal Usuario
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-009.1.1 | Dashboard | Panel principal | Alta |
| F-009.1.2 | Predicciones | CRUD predicciones | Alta |
| F-009.1.3 | Modelos | Explorar modelos | Alta |
| F-009.1.4 | Perfil | Gestion personal | Media |
### F-009.2: Portal Admin Cliente
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-009.2.1 | Dashboard | Metricas tenant | Alta |
| F-009.2.2 | Usuarios | Gestion usuarios | Alta |
| F-009.2.3 | Facturacion | Planes y pagos | Alta |
| F-009.2.4 | Reportes | Uso y consumo | Media |
### F-009.3: Portal Admin SaaS
| ID | Funcionalidad | Descripcion | Prioridad |
|----|---------------|-------------|-----------|
| F-009.3.1 | Dashboard | Metricas globales | Alta |
| F-009.3.2 | Tenants | Gestion tenants | Alta |
| F-009.3.3 | Planes | Config planes | Alta |
| F-009.3.4 | Sistema | Config global | Media |
---
## Dependencias
```yaml
Dependencias:
- BA-007 (tenants): Multi-tenancy
- BA-008 (payments): Facturacion
- BA-001 (auth): Autenticacion y roles
Catalogos:
- shared/catalog/portales/
```
---
## Criterios de Aceptacion
- [ ] Usuario ve solo su portal correspondiente
- [ ] Navegacion es clara y contextual
- [ ] Permisos se aplican correctamente
- [ ] Dashboard muestra metricas relevantes
- [ ] Responsive en todos los dispositivos
---
**Documento generado por:** NEXUS Orchestration
**Fecha:** 2026-01-04

39
docs/02-definicion-modulos/_INDEX.md Normal file
View File

@ -0,0 +1,39 @@
---
id: "BA-MODULES-INDEX"
title: "Indice de Modulos - Betting Analytics"
type: "Index"
status: "Active"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# Indice de Modulos - Betting Analytics
## Modulos Funcionales
| ID | Nombre | Estado | Descripcion |
|----|--------|--------|-------------|
| BA-001 | Fundamentos | Planned | Auth, usuarios base |
| BA-002 | Ingestion de Datos | Backlog | Fuentes de datos deportivos |
| BA-003 | Analytics Engine | Backlog | Motor de analisis |
| BA-004 | Predicciones ML | Backlog | Modelos predictivos |
| BA-005 | Reportes | Backlog | Dashboard y reportes |
## Modulos SaaS
| ID | Nombre | Estado | Descripcion |
|----|--------|--------|-------------|
| BA-007 | Tenants | Draft | Multi-tenancy con RLS |
| BA-008 | Payments | Draft | Integracion Stripe |
| BA-009 | Portals | Draft | 3 portales diferenciados |
---
## Referencias
- [BA-007-TENANTS](./BA-007-TENANTS.md)
- [BA-008-PAYMENTS](./BA-008-PAYMENTS.md)
- [BA-009-PORTALS](./BA-009-PORTALS.md)

285
docs/04-fase-backlog/DEFINITION-OF-DONE.md Normal file
View File

@ -0,0 +1,285 @@
---
id: "DOD-BA"
title: "Definition of Done - Betting Analytics"
type: "Process"
status: "Approved"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# Definition of Done (DoD) - Betting Analytics
---
## 1. PROPOSITO
La Definition of Done establece los criterios que un item debe cumplir para considerarse COMPLETADO. Garantiza calidad consistente y evita deuda tecnica.
---
## 2. CRITERIOS GENERALES
### 2.1 Codigo
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Implementado** | Codigo funcional que cumple requisitos | Si |
| **Revisado** | Code review aprobado por otro agente | Si |
| **Sin warnings** | ESLint/TSC sin errores ni warnings | Si |
| **Formateado** | Prettier aplicado | Si |
| **Tipado** | Sin `any` innecesarios | Si |
### 2.2 Testing
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Tests unitarios** | Coverage minimo 80% | Si |
| **Tests pasando** | Todos los tests en verde | Si |
| **Tests E2E** | Flujos criticos cubiertos | Deseable |
| **Tests manuales** | Funcionalidad verificada | Si |
### 2.3 Documentacion
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **API documentada** | Endpoints en Swagger/OpenAPI | Si (si aplica) |
| **Codigo comentado** | Logica compleja documentada | Deseable |
| **README actualizado** | Si hay cambios de setup | Si (si aplica) |
| **_MAP.md actualizado** | Navegacion actualizada | Si |
### 2.4 Calidad
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Sin bugs conocidos** | No deja bugs abiertos | Si |
| **Performance OK** | Cumple benchmarks si aplica | Deseable |
| **Seguridad OK** | Sin vulnerabilidades obvias | Si |
| **Accesibilidad** | Cumple basicos si es UI | Deseable |
### 2.5 Deploy
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Build exitoso** | CI/CD en verde | Si |
| **Deployable** | Puede desplegarse a staging | Si |
| **Smoke tests** | Funciona en ambiente destino | Si |
---
## 3. CRITERIOS POR TIPO
### 3.1 User Story (US)
```markdown
## Checklist DoD - User Story
### Codigo
- [ ] Implementacion completa de todos los criterios de aceptacion
- [ ] Code review aprobado
- [ ] Sin warnings de linter
- [ ] Codigo formateado con Prettier
- [ ] Sin uso de `any` sin justificacion
### Testing
- [ ] Tests unitarios con coverage >= 80%
- [ ] Todos los tests pasando
- [ ] Tests de integracion si aplica
- [ ] Prueba manual exitosa
### Documentacion
- [ ] API endpoints documentados (Swagger)
- [ ] Comentarios en logica compleja
- [ ] YAML front-matter actualizado con:
- status: "Done"
- completed_date: "YYYY-MM-DD"
### Calidad
- [ ] Criterios de aceptacion verificados
- [ ] Sin bugs conocidos pendientes
- [ ] Performance aceptable
- [ ] Sin vulnerabilidades de seguridad
### Deploy
- [ ] Build exitoso
- [ ] Merge a develop/main sin conflictos
- [ ] Funciona en ambiente de desarrollo
```
### 3.2 Task (TASK)
```markdown
## Checklist DoD - Task
- [ ] Trabajo tecnico completado
- [ ] Resultado esperado logrado
- [ ] Code review (si aplica)
- [ ] Tests actualizados (si aplica)
- [ ] Documentacion actualizada (si aplica)
- [ ] YAML actualizado: status: "Done", completed_date
```
### 3.3 Bug (BUG)
```markdown
## Checklist DoD - Bug
- [ ] Bug corregido
- [ ] Causa raiz identificada
- [ ] Regression test creado
- [ ] Probado en ambiente de desarrollo
- [ ] No introduce nuevos bugs
- [ ] YAML actualizado: status: "Done", resolved_date, fix_commit
```
---
## 4. PROCESO DE VALIDACION
### 4.1 Quien Valida
| Item | Validador Principal | Validador Secundario |
|------|---------------------|----------------------|
| US Backend | @Frontend-Agent | @Tech-Lead |
| US Frontend | @Backend-Agent | @Tech-Lead |
| Task | Peer del mismo equipo | - |
| Bug | @QA-Agent | Autor del fix |
### 4.2 Flujo de Validacion
```
Desarrollo -> Code Review -> Tests -> QA -> DoD Check -> Done
```
1. **Desarrollo:** Agente implementa el item
2. **Code Review:** Otro agente revisa el codigo
3. **Tests:** Verificar que tests pasan
4. **QA:** Prueba manual de funcionalidad
5. **DoD Check:** Verificar checklist completo
6. **Done:** Mover a columna "Hecho" en Board.md
### 4.3 Rechazo
Si un item no pasa DoD:
1. Documentar razon del rechazo
2. Regresar a "En Progreso"
3. Agregar nota en el item
4. Notificar al agente responsable
---
## 5. YAML FRONT-MATTER DONE
### User Story Done
```yaml
---
id: "US-BA-XXX"
title: "Titulo descriptivo"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "BA-XXX"
story_points: X
labels: ["modulo", "feature"]
assignee: "@Agente"
created_date: "YYYY-MM-DD"
updated_date: "YYYY-MM-DD"
completed_date: "YYYY-MM-DD"
reviewer: "@Reviewer-Agent"
---
```
### Bug Done
```yaml
---
id: "BUG-BA-XXX"
title: "Descripcion del bug"
type: "Bug"
status: "Done"
severity: "P1"
affected_module: "Backend"
created_date: "YYYY-MM-DD"
resolved_date: "YYYY-MM-DD"
fix_commit: "abc123def"
root_cause: "Descripcion de la causa raiz"
---
```
---
## 6. EXCEPCIONES
### Cuando se puede relajar DoD
| Situacion | Criterios relajables | Aprobador |
|-----------|---------------------|-----------|
| Hotfix Produccion | Tests E2E, Docs completos | @PO-Agent |
| Spike | Tests coverage, Docs API | @Tech-Lead |
| POC | Todos excepto funcionalidad | @PO-Agent |
### Documentar Excepciones
Agregar al item:
```markdown
## Excepcion DoD
**Fecha:** YYYY-MM-DD
**Aprobador:** @Agente
**Criterios omitidos:** [lista]
**Razon:** [justificacion]
**Deuda tecnica:** [items a completar despues]
```
---
## 7. DEUDA TECNICA
### Registro de Deuda
Si se acepta una excepcion, crear tarea de deuda:
```yaml
---
id: "TASK-BA-DEBT-XXX"
title: "Completar DoD para US-BA-XXX"
type: "Task"
status: "To Do"
priority: "P2"
labels: ["tech-debt", "dod"]
parent_us: "US-BA-XXX"
created_date: "YYYY-MM-DD"
---
```
---
## 8. METRICAS
### KPIs de DoD
| Metrica | Target | Actual |
|---------|--------|--------|
| % Items que pasan DoD primera vez | >80% | - |
| Items con excepciones por Sprint | <2 | - |
| Deuda tecnica acumulada | <5 items | - |
| Bugs por US completada | <0.5 | - |
---
## 9. REFERENCIAS
- **DoR:** [DEFINITION-OF-READY.md](./DEFINITION-OF-READY.md)
- **Board:** [../planning/Board.md](../planning/Board.md)
- **Config:** [../planning/config.yml](../planning/config.yml)
- **AGENTS:** [../../AGENTS.md](../../AGENTS.md)
---
**Documento:** Definition of Done
**Proyecto:** Betting Analytics
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Approved

227
docs/04-fase-backlog/DEFINITION-OF-READY.md Normal file
View File

@ -0,0 +1,227 @@
---
id: "DOR-BA"
title: "Definition of Ready - Betting Analytics"
type: "Process"
status: "Approved"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# Definition of Ready (DoR) - Betting Analytics
---
## 1. PROPOSITO
La Definition of Ready establece los criterios que un item del backlog debe cumplir ANTES de poder ser incluido en un Sprint. Garantiza que el equipo tenga toda la informacion necesaria para estimar y ejecutar el trabajo.
---
## 2. CRITERIOS GENERALES
### 2.1 Claridad
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Titulo descriptivo** | El titulo refleja claramente el objetivo | Si |
| **Descripcion completa** | Problema y solucion documentados | Si |
| **Sin ambiguedades** | Sin preguntas abiertas bloqueantes | Si |
| **Lenguaje entendible** | Cualquier agente puede entenderlo | Si |
### 2.2 Criterios de Aceptacion
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Definidos** | Al menos 2 criterios de aceptacion | Si |
| **Medibles** | Pueden ser verificados objetivamente | Si |
| **Completos** | Cubren el alcance del item | Si |
### 2.3 Alcance
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Scope delimitado** | Bordes claros del trabajo | Si |
| **Tamano adecuado** | Completable en 1 Sprint | Si |
| **Independiente** | Minimas dependencias externas | Deseable |
### 2.4 Dependencias
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Identificadas** | Todas las dependencias listadas | Si |
| **Resueltas** | Dependencias bloqueantes resueltas | Si |
| **Ordenadas** | Secuencia de trabajo clara | Deseable |
### 2.5 Estimacion
| Criterio | Descripcion | Obligatorio |
|----------|-------------|-------------|
| **Story Points** | Estimacion en SP asignada | Si |
| **Complejidad** | Complejidad evaluada (baja/media/alta) | Si |
| **Riesgos** | Riesgos identificados | Deseable |
---
## 3. CRITERIOS POR TIPO
### 3.1 User Story (US)
```markdown
## Checklist DoR - User Story
### Claridad
- [ ] Tiene formato "Como [rol], quiero [accion], para [beneficio]"
- [ ] Contexto de negocio documentado
- [ ] Sin preguntas abiertas
### Criterios de Aceptacion
- [ ] Minimo 2 criterios de aceptacion
- [ ] Criterios verificables y medibles
- [ ] Escenarios edge-case considerados
### Alcance
- [ ] Scope claramente delimitado
- [ ] Tamano <= 13 SP (o dividir)
- [ ] Puede completarse en 1 Sprint
### Dependencias
- [ ] US dependientes identificadas
- [ ] APIs/servicios externos disponibles
- [ ] Datos de prueba disponibles
### Estimacion
- [ ] Story Points asignados
- [ ] Complejidad evaluada
- [ ] Tareas tecnicas identificadas
### Documentacion
- [ ] YAML front-matter completo
- [ ] Epic asignada
- [ ] Labels apropiados
```
### 3.2 Task (TASK)
```markdown
## Checklist DoR - Task
- [ ] Descripcion clara del trabajo tecnico
- [ ] Resultado esperado definido
- [ ] Estimacion en horas
- [ ] Dependencias tecnicas identificadas
- [ ] YAML front-matter completo
```
### 3.3 Bug (BUG)
```markdown
## Checklist DoR - Bug
- [ ] Descripcion del error
- [ ] Pasos para reproducir
- [ ] Comportamiento esperado vs actual
- [ ] Severidad asignada
- [ ] Modulo afectado identificado
- [ ] Evidencia (logs, screenshots)
```
---
## 4. PROCESO DE VALIDACION
### 4.1 Quien Valida
| Item | Validador Principal | Validador Secundario |
|------|---------------------|----------------------|
| US | @PO-Agent | @Tech-Lead-Agent |
| Task | @Tech-Lead-Agent | @Backend-Agent |
| Bug | @QA-Agent | @Backend-Agent |
### 4.2 Cuando Validar
1. **Antes de Sprint Planning:** Revisar items candidatos
2. **Durante Refinement:** Detallar items del backlog
3. **Al crear item:** Verificar checklist inicial
### 4.3 Como Validar
1. Revisar checklist correspondiente al tipo
2. Verificar que todos los obligatorios estan completos
3. Marcar item como "Ready" en Board.md
4. Mover a columna "Por Hacer" si aplica
---
## 5. YAML FRONT-MATTER REQUERIDO
### User Story Ready
```yaml
---
id: "US-BA-XXX"
title: "Titulo descriptivo"
type: "User Story"
status: "To Do" # Indica que paso DoR
priority: "Alta"
epic: "BA-XXX"
story_points: X
labels: ["modulo", "feature"]
created_date: "YYYY-MM-DD"
updated_date: "YYYY-MM-DD"
ready_date: "YYYY-MM-DD" # Fecha que paso DoR
---
```
---
## 6. EXCEPCIONES
### Cuando se puede relajar DoR
| Situacion | Criterios relajables | Aprobador |
|-----------|---------------------|-----------|
| Bug Critico (P0) | Estimacion | @PO-Agent |
| Spike/Investigacion | Criterios de aceptacion | @Tech-Lead |
| Hotfix | Documentacion completa | @PO-Agent |
### Documentar Excepciones
Agregar al item:
```markdown
## Excepcion DoR
**Fecha:** YYYY-MM-DD
**Aprobador:** @Agente
**Criterios omitidos:** [lista]
**Razon:** [justificacion]
```
---
## 7. METRICAS
### KPIs de DoR
| Metrica | Target | Actual |
|---------|--------|--------|
| % Items que pasan DoR | 100% | - |
| Items rechazados por Sprint | <2 | - |
| Tiempo promedio de refinement | <2h | - |
---
## 8. REFERENCIAS
- **DoD:** [DEFINITION-OF-DONE.md](./DEFINITION-OF-DONE.md)
- **Board:** [../planning/Board.md](../planning/Board.md)
- **Config:** [../planning/config.yml](../planning/config.yml)
- **AGENTS:** [../../AGENTS.md](../../AGENTS.md)
---
**Documento:** Definition of Ready
**Proyecto:** Betting Analytics
**Version:** 1.0.0
**Fecha:** 2026-01-04
**Estado:** Approved

51
docs/04-fase-backlog/_MAP.md Normal file
View File

@ -0,0 +1,51 @@
---
id: "MAP-04-BACKLOG"
title: "Mapa de Navegacion - Fase Backlog"
type: "Navigation"
folder: "04-fase-backlog"
updated_date: "2026-01-04"
---
# _MAP: 04-fase-backlog
**Carpeta:** Fase Backlog
**Proyecto:** Betting Analytics
**Actualizado:** 2026-01-04
---
## Proposito
Esta carpeta contiene las definiciones de proceso para el backlog del proyecto, incluyendo Definition of Ready (DoR) y Definition of Done (DoD).
---
## Contenido
| Archivo | Titulo | Estado | Descripcion |
|---------|--------|--------|-------------|
| [DEFINITION-OF-READY.md](./DEFINITION-OF-READY.md) | Definition of Ready | Approved | Criterios para items "Ready" |
| [DEFINITION-OF-DONE.md](./DEFINITION-OF-DONE.md) | Definition of Done | Approved | Criterios para items "Done" |
---
## Estadisticas
| Metrica | Valor |
|---------|-------|
| Total documentos | 2 |
| Estado Approved | 2 |
| Estado Draft | 0 |
---
## Referencias
- **Nivel superior:** [../README.md](../README.md)
- **Mapa principal:** [../_MAP.md](../_MAP.md)
- **Board:** [../planning/Board.md](../planning/Board.md)
---
**Generado:** 2026-01-04
**Mantenedor:** @Doc-Agent

230
docs/97-adr/ADR-001-stack-tecnologico.md Normal file
View File

@ -0,0 +1,230 @@
---
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

85
docs/97-adr/README.md Normal file
View File

@ -0,0 +1,85 @@
---
id: "ADR-INDEX"
title: "Indice de ADRs - Betting Analytics"
type: "Index"
updated_date: "2026-01-04"
---
# Architecture Decision Records (ADRs)
**Proyecto:** Betting Analytics
**Actualizado:** 2026-01-04
---
## Proposito
Los Architecture Decision Records (ADRs) documentan las decisiones arquitectonicas significativas del proyecto, incluyendo el contexto, alternativas consideradas, decision tomada y consecuencias.
---
## Indice de ADRs
| ID | Titulo | Status | Fecha | Tags |
|----|--------|--------|-------|------|
| [ADR-001](./ADR-001-stack-tecnologico.md) | Stack Tecnologico Base | Accepted | 2026-01-04 | architecture, stack, backend, frontend |
---
## Estados de ADR
| Estado | Descripcion |
|--------|-------------|
| **Proposed** | En discusion, pendiente de decision |
| **Accepted** | Decision tomada y vigente |
| **Deprecated** | Ya no es relevante |
| **Superseded** | Reemplazado por otro ADR |
---
## Como crear un nuevo ADR
1. Copiar template desde `ADR-001-stack-tecnologico.md`
2. Asignar siguiente numero secuencial
3. Completar todas las secciones
4. Agregar a este indice
5. Commit con mensaje: `Add ADR-XXX: [titulo]`
---
## Template basico
```markdown
---
id: "ADR-XXX"
title: "Titulo de la Decision"
type: "ADR"
status: "Proposed"
date: "YYYY-MM-DD"
deciders: ["@Agente1", "@Agente2"]
tags: ["tag1", "tag2"]
---
# ADR-XXX: Titulo
## Context
[Problema o situacion]
## Decision
[Decision tomada]
## Consequences
[Impacto positivo y negativo]
```
---
## Referencias
- **Vision:** [../00-vision-general/VISION-PRODUCTO.md](../00-vision-general/VISION-PRODUCTO.md)
- **Arquitectura:** [../00-vision-general/ARQUITECTURA-GENERAL.md](../00-vision-general/ARQUITECTURA-GENERAL.md)
- **Stack:** [../00-vision-general/STACK-TECNOLOGICO.md](../00-vision-general/STACK-TECNOLOGICO.md)
---
**Mantenedor:** @Tech-Lead

53
docs/97-adr/_MAP.md Normal file
View File

@ -0,0 +1,53 @@
---
id: "MAP-97-ADR"
title: "Mapa de Navegacion - ADRs"
type: "Navigation"
folder: "97-adr"
updated_date: "2026-01-04"
---
# _MAP: 97-adr
**Carpeta:** Architecture Decision Records
**Proyecto:** Betting Analytics
**Actualizado:** 2026-01-04
---
## Proposito
Esta carpeta contiene los Architecture Decision Records (ADRs) que documentan las decisiones arquitectonicas significativas del proyecto.
---
## Contenido
| Archivo | Titulo | Estado | Fecha |
|---------|--------|--------|-------|
| [README.md](./README.md) | Indice de ADRs | - | 2026-01-04 |
| [ADR-001-stack-tecnologico.md](./ADR-001-stack-tecnologico.md) | Stack Tecnologico Base | Accepted | 2026-01-04 |
---
## Estadisticas
| Metrica | Valor |
|---------|-------|
| Total ADRs | 1 |
| Accepted | 1 |
| Proposed | 0 |
| Deprecated | 0 |
| Superseded | 0 |
---
## Referencias
- **Nivel superior:** [../README.md](../README.md)
- **Mapa principal:** [../_MAP.md](../_MAP.md)
- **Arquitectura:** [../00-vision-general/ARQUITECTURA-GENERAL.md](../00-vision-general/ARQUITECTURA-GENERAL.md)
---
**Generado:** 2026-01-04
**Mantenedor:** @Tech-Lead

198
docs/99-analisis/ANALISIS-SAAS-MULTITENANCY.md Normal file
View File

@ -0,0 +1,198 @@
---
id: "ANALISIS-SAAS-BA"
title: "Analisis SaaS - Multi-tenancy y Pagos"
type: "Analysis"
status: "Draft"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# Analisis SaaS: Multi-tenancy y Pagos
**Fecha:** 2026-01-04
**Proyecto:** Betting Analytics
---
## 1. Estado Actual
### 1.1 Estructura de Documentacion
| Carpeta | Estado | Contenido |
|---------|--------|-----------|
| 00-vision-general | Existe | VISION-PRODUCTO, ARQUITECTURA, STACK |
| 01-fase-alcance-inicial | Existe | BA-001-fundamentos (planificado) |
| 02-definicion-modulos | NO EXISTE | Debe crearse |
| 04-fase-backlog | Existe | DoR, DoD |
| 97-adr | Existe | ADR-001 stack |
### 1.2 EPICs Existentes
| ID | Nombre | Estado |
|----|--------|--------|
| BA-001 | Fundamentos | Planned |
| BA-002 | Ingestion de Datos | Backlog |
| BA-003 | Analytics Engine | Backlog |
| BA-004 | Predicciones ML | Backlog |
| BA-005 | Reportes y Dashboard | Backlog |
### 1.3 Referencias SaaS Actuales
| Elemento | Estado |
|----------|--------|
| Multi-tenancy | Mencionado en roadmap (largo plazo) |
| Planes de suscripcion | No definido |
| Stripe/Pagos | No existe |
| Portales diferenciados | No existe |
---
## 2. Gaps Identificados
### 2.1 Modulos Faltantes
| Modulo | Prioridad | Descripcion |
|--------|-----------|-------------|
| BA-007-TENANTS | Alta | Multi-tenancy con RLS |
| BA-008-PAYMENTS | Alta | Integracion Stripe |
| BA-009-PORTALS | Alta | 3 portales diferenciados |
### 2.2 Actualizaciones Requeridas
| Archivo | Cambios |
|---------|---------|
| VISION-PRODUCTO.md | Agregar seccion SaaS y planes |
| ARQUITECTURA-GENERAL.md | Agregar modulos Payments, Portales |
| STACK-TECNOLOGICO.md | Agregar Stripe SDK |
---
## 3. Planes de Suscripcion Propuestos
| Plan | Precio | Predicciones/mes | Modelos ML | Historico | Soporte |
|------|--------|------------------|------------|-----------|---------|
| Free | $0 | 50 | 1 basico | 30 dias | Comunidad |
| Pro | $39/mes | 500 | 3 avanzados | 1 ano | Email |
| Enterprise | $149/mes | Ilimitado | Custom | Ilimitado | Dedicado |
### Productos Stripe
```yaml
Productos:
ba_pro:
type: subscription
precio: $39/mes
stripe_price_id: TBD
ba_enterprise:
type: subscription
precio: $149/mes
stripe_price_id: TBD
ba_predictions_100:
type: one_time
precio: $9
descripcion: "100 predicciones adicionales"
```
---
## 4. Estructura de 3 Portales
### Portal 1: Usuario General (Analyst)
- Dashboard personal de predicciones
- Acceso a modelos segun plan
- Historial de predicciones
- Perfil y configuracion
### Portal 2: Admin Cliente (Tenant Admin)
- Dashboard de organizacion
- Gestion de usuarios del tenant
- Configuracion y limites
- Facturacion y suscripcion
- Reportes de uso
### Portal 3: Admin SaaS (Super Admin)
- Dashboard global de todos los tenants
- Gestion de planes y precios
- Monitoreo de sistema
- Soporte y tickets
- Analytics globales
---
## 5. Plan de Ejecucion
### 5.1 Archivos a Crear
| Archivo | Tipo | Contenido |
|---------|------|-----------|
| 02-definicion-modulos/_INDEX.md | Index | Indice de modulos |
| BA-007-TENANTS.md | Module | Multi-tenancy con RLS |
| BA-008-PAYMENTS.md | Module | Integracion Stripe |
| BA-009-PORTALS.md | Module | 3 portales |
### 5.2 Archivos a Modificar
| Archivo | Cambios |
|---------|---------|
| VISION-PRODUCTO.md | Seccion 10: Modelo SaaS |
| ARQUITECTURA-GENERAL.md | Componentes Payments, Portals |
| STACK-TECNOLOGICO.md | Stripe SDK en dependencias |
---
## 6. Validacion vs Requisitos
| Requisito | Estado | Archivo |
|-----------|--------|---------|
| Multi-tenancy | A crear | BA-007-TENANTS |
| Planes de suscripcion | A crear | BA-008-PAYMENTS |
| Integracion Stripe | A crear | BA-008-PAYMENTS |
| Portal Usuario | A crear | BA-009-PORTALS |
| Portal Admin Cliente | A crear | BA-009-PORTALS |
| Portal Admin SaaS | A crear | BA-009-PORTALS |
---
**Estado:** ✅ COMPLETADO
---
## 7. Ejecucion Completada (Fases 5-8)
### 7.1 Archivos Creados
| Archivo | Lineas | Contenido |
|---------|--------|-----------|
| 02-definicion-modulos/_INDEX.md | ~45 | Indice de modulos |
| BA-007-TENANTS.md | ~190 | Multi-tenancy con RLS |
| BA-008-PAYMENTS.md | ~250 | Integracion Stripe completa |
| BA-009-PORTALS.md | ~280 | 3 portales diferenciados |
### 7.2 Archivos Modificados
| Archivo | Cambios |
|---------|---------|
| VISION-PRODUCTO.md | +85 lineas (Seccion 10: Modelo SaaS) |
| STACK-TECNOLOGICO.md | +1 linea (Stripe SDK) |
### 7.3 Validacion Final
| Requisito | Estado | Archivo |
|-----------|--------|---------|
| Multi-tenancy | ✅ | BA-007-TENANTS.md |
| Planes de suscripcion | ✅ | BA-008-PAYMENTS.md |
| Integracion Stripe | ✅ | BA-008-PAYMENTS.md |
| Webhooks Stripe | ✅ | BA-008-PAYMENTS.md |
| Portal Usuario | ✅ | BA-009-PORTALS.md |
| Portal Admin Cliente | ✅ | BA-009-PORTALS.md |
| Portal Admin SaaS | ✅ | BA-009-PORTALS.md |
| YAML front-matter | ✅ | 100% de archivos |
**Total archivos nuevos:** 4
**Total archivos modificados:** 2
**Estado general:** COMPLETADO

175
docs/README.md
View File

@ -1,38 +1,163 @@
# DOCUMENTACIÓN - Betting Analytics ---
id: "README-DOCS-BA"
title: "Documentacion - Betting Analytics"
type: "Index"
project: "betting-analytics"
version: "1.0.0"
status: "Active"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
# Documentacion - Betting Analytics
**Proyecto:** Betting Analytics **Proyecto:** Betting Analytics
**Versión:** 1.0.0 **Version:** 0.1.0
**Fecha:** 2025-12-05 **Estado:** Planificacion
**Estado:** Por iniciar **Sistema:** NEXUS v3.4 + SIMCO + SCRUM
--- ---
## Estructura de Documentación ## Acerca del Proyecto
``` **Betting Analytics** es una plataforma de analisis de apuestas deportivas que combina:
docs/
├── 00-vision-general/ # Visión, objetivos y alcance - **Ingestion de datos** en tiempo real
├── 01-analisis-referencias/ # Análisis de sistemas de referencia - **Analytics avanzado** con metricas estadisticas
├── 02-definicion-modulos/ # Lista, índice y dependencias de módulos - **Modelos predictivos** basados en Machine Learning
├── 03-requerimientos/ # Requerimientos funcionales por módulo - **Dashboard interactivo** para visualizacion
├── 04-modelado/ # Diseño técnico
│ ├── database-design/ # DDL specs, schemas ### Stack Tecnologico
│ ├── domain-models/ # Modelos de dominio
│ └── especificaciones-tecnicas/ # ET backend/frontend | Componente | Tecnologia |
├── 05-user-stories/ # Historias de usuario |------------|------------|
├── 06-test-plans/ # Planes de prueba | Backend | NestJS + TypeORM |
├── 07-devops/ # CI/CD, infraestructura | Frontend | React + Vite |
├── 90-transversal/ # Documentos transversales | ML Engine | Python + FastAPI |
├── 95-guias-desarrollo/ # Guías para desarrolladores | Database | PostgreSQL |
└── 97-adr/ # Architecture Decision Records | Container | Docker |
```
--- ---
## Directiva Aplicable ## Estructura de Documentacion
Ver: `/workspace/core/orchestration/directivas/DIRECTIVA-ESTRUCTURA-DOCUMENTACION-PROYECTOS.md` | Carpeta | Contenido | Estado |
|---------|-----------|--------|
| [00-vision-general/](./00-vision-general/) | Vision, arquitectura, stack | 3 docs |
| [01-fase-alcance-inicial/](./01-fase-alcance-inicial/) | EPICs del MVP | Planificada |
| [04-fase-backlog/](./04-fase-backlog/) | DoR, DoD, backlog | 2 docs |
| [90-transversal/](./90-transversal/) | Inventarios, transversal | Pendiente |
| [95-guias-desarrollo/](./95-guias-desarrollo/) | Guias para devs | Pendiente |
| [96-quick-reference/](./96-quick-reference/) | Cheatsheets | Pendiente |
| [97-adr/](./97-adr/) | Decisiones arquitectura | 1 ADR |
| [planning/](./planning/) | Board, config, sprints | Activo |
| [archivados/](./archivados/) | Historicos | - |
--- ---
**Última actualización:** 2025-12-05 ## Documentos Clave
### Para Entender el Proyecto
1. **[Vision del Producto](./00-vision-general/VISION-PRODUCTO.md)** - Objetivos, usuarios, propuesta de valor
2. **[Arquitectura General](./00-vision-general/ARQUITECTURA-GENERAL.md)** - Componentes, flujos, modelo de datos
3. **[Stack Tecnologico](./00-vision-general/STACK-TECNOLOGICO.md)** - Tecnologias y dependencias
### Para Trabajar en el Proyecto
1. **[AGENTS.md](../AGENTS.md)** - Guia para agentes IA
2. **[Board.md](./planning/Board.md)** - Tablero Kanban activo
3. **[Definition of Ready](./04-fase-backlog/DEFINITION-OF-READY.md)** - Criterios para items "Ready"
4. **[Definition of Done](./04-fase-backlog/DEFINITION-OF-DONE.md)** - Criterios para items "Done"
### Decisiones Arquitectonicas
1. **[ADR-001: Stack Tecnologico](./97-adr/ADR-001-stack-tecnologico.md)** - Eleccion de tecnologias
---
## Navegacion
- **Mapa Completo:** [_MAP.md](./_MAP.md)
- **Configuracion:** [planning/config.yml](./planning/config.yml)
- **Board Activo:** [planning/Board.md](./planning/Board.md)
---
## EPICs del Proyecto
| ID | Nombre | Descripcion | Estado |
|----|--------|-------------|--------|
| BA-001 | Fundamentos | Estructura, auth, API base | Planificada |
| BA-002 | Ingestion de Datos | Conectores, pipelines | Backlog |
| BA-003 | Analytics Engine | Metricas, dashboard | Backlog |
| BA-004 | Predicciones ML | Modelos, backtesting | Backlog |
| BA-005 | Reportes | Visualizaciones, exportacion | Backlog |
---
## Estado del Proyecto
### Sprint Actual: Sprint-0 (Planificacion)
| Metrica | Valor |
|---------|-------|
| SP Planificados | 0 |
| SP Completados | 0 |
| Bugs Abiertos | 0 |
| US en Backlog | 3 |
### Documentacion
| Tipo | Total | Con YAML |
|------|-------|----------|
| Vision/Arquitectura | 3 | 3 (100%) |
| DoR/DoD | 2 | 2 (100%) |
| ADRs | 1 | 1 (100%) |
| _MAP.md | 4 | 4 (100%) |
---
## Codigo Fuente
| Componente | Ubicacion | Puerto |
|------------|-----------|--------|
| Backend | [apps/backend/](../apps/backend/) | 3090 |
| Frontend | [apps/frontend/](../apps/frontend/) | 80 |
| ML Engine | [apps/ml/](../apps/ml/) | 3093 |
---
## Contribuir
### Para Agentes IA
1. Leer [AGENTS.md](../AGENTS.md) antes de empezar
2. Revisar [Board.md](./planning/Board.md) para tareas disponibles
3. Seguir [DoR](./04-fase-backlog/DEFINITION-OF-READY.md) y [DoD](./04-fase-backlog/DEFINITION-OF-DONE.md)
4. Actualizar documentacion con cada cambio
### Nomenclatura
- EPICs: `BA-NNN` (ej: BA-001)
- User Stories: `US-BA-NNN` (ej: US-BA-001)
- Tasks: `TASK-BA-NNN` (ej: TASK-BA-001)
- Bugs: `BUG-BA-NNN` (ej: BUG-BA-001)
- ADRs: `ADR-NNN` (ej: ADR-001)
---
## Referencias
| Recurso | Link |
|---------|------|
| README Principal | [../README.md](../README.md) |
| AGENTS.md | [../AGENTS.md](../AGENTS.md) |
| INVENTARIO.yml | [../INVENTARIO.yml](../INVENTARIO.yml) |
| Orchestration | [../orchestration/](../orchestration/) |
---
**Ultima actualizacion:** 2026-01-04
**Mantenedor:** @Doc-Agent
**Sistema:** NEXUS v3.4 + SIMCO + SCRUM

152
docs/_MAP.md
View File

@ -1,8 +1,18 @@
# Mapa de Documentacion: betting-analytics ---
id: "MAP-DOCS-BA"
title: "Mapa de Documentacion - Betting Analytics"
type: "Navigation"
project: "betting-analytics"
version: "1.0.0"
updated_date: "2026-01-04"
---
**Proyecto:** betting-analytics # Mapa de Documentacion: Betting Analytics
**Proyecto:** Betting Analytics
**Prefijo:** BA
**Sistema:** NEXUS v3.4 + SIMCO + SCRUM
**Actualizado:** 2026-01-04 **Actualizado:** 2026-01-04
**Generado por:** EPIC-008 adapt-simco.sh
--- ---
@ -10,31 +20,119 @@
``` ```
docs/ docs/
├── _MAP.md # Este archivo (indice de navegacion) ├── _MAP.md # Este archivo (navegacion principal)
├── 00-overview/ # Vision general del proyecto ├── README.md # Indice principal
├── 01-architecture/ # Arquitectura y decisiones (ADRs) │
├── 02-specs/ # Especificaciones tecnicas ├── 00-vision-general/ # Vision y arquitectura
├── 03-api/ # Documentacion de APIs │ ├── _MAP.md
├── 04-guides/ # Guias de desarrollo │ ├── VISION-PRODUCTO.md # Vision del producto
└── 99-finiquito/ # Entregables cliente (si aplica) │ ├── ARQUITECTURA-GENERAL.md # Arquitectura del sistema
│ └── STACK-TECNOLOGICO.md # Stack y tecnologias
│
├── 01-fase-alcance-inicial/ # EPICs del MVP
│ └── BA-001-fundamentos/ # EPIC: Fundamentos (planificada)
│
├── 04-fase-backlog/ # Backlog y procesos
│ ├── _MAP.md
│ ├── DEFINITION-OF-READY.md # Criterios DoR
│ └── DEFINITION-OF-DONE.md # Criterios DoD
│
├── 90-transversal/ # Documentacion transversal
│ ├── arquitectura/ # Diagramas, decisiones
│ └── inventarios/ # Inventarios de componentes
│
├── 95-guias-desarrollo/ # Guias para desarrolladores
│
├── 96-quick-reference/ # Cheatsheets
│
├── 97-adr/ # Architecture Decision Records
│ ├── _MAP.md
│ ├── README.md # Indice de ADRs
│ └── ADR-001-stack-tecnologico.md # Stack tecnologico
│
├── planning/ # Planificacion activa
│ ├── Board.md # Tablero Kanban
│ ├── config.yml # Configuracion SCRUM
│ ├── tasks/ # Tareas activas
│ └── bugs/ # Bugs activos
│
└── archivados/ # Documentacion historica
``` ```
## Navegacion Rapida
| Seccion | Descripcion | Estado |
|---------|-------------|--------|
| Overview | Vision general | - |
| Architecture | Decisiones arquitectonicas | - |
| Specs | Especificaciones tecnicas | - |
| API | Documentacion de endpoints | - |
| Guides | Guias de desarrollo | - |
## Estadisticas
- Total archivos en docs/: 1
- Fecha de adaptacion: 2026-01-04
--- ---
**Nota:** Este archivo fue generado automaticamente por EPIC-008. ## Navegacion Rapida
Actualizar manualmente con la estructura real del proyecto.
### Documentacion Principal
| Seccion | Descripcion | Estado |
|---------|-------------|--------|
| [00-vision-general/](./00-vision-general/) | Vision, arquitectura, stack | 3 docs |
| [04-fase-backlog/](./04-fase-backlog/) | DoR, DoD, backlog | 2 docs |
| [97-adr/](./97-adr/) | Decisiones arquitectonicas | 1 ADR |
| [planning/](./planning/) | Board Kanban, config | Activo |
### Documentos Clave
| Documento | Descripcion | Link |
|-----------|-------------|------|
| Vision del Producto | Objetivos y propuesta de valor | [VISION-PRODUCTO.md](./00-vision-general/VISION-PRODUCTO.md) |
| Arquitectura | Componentes y flujos | [ARQUITECTURA-GENERAL.md](./00-vision-general/ARQUITECTURA-GENERAL.md) |
| Stack Tecnologico | Tecnologias y dependencias | [STACK-TECNOLOGICO.md](./00-vision-general/STACK-TECNOLOGICO.md) |
| Definition of Ready | Criterios para items "Ready" | [DEFINITION-OF-READY.md](./04-fase-backlog/DEFINITION-OF-READY.md) |
| Definition of Done | Criterios para items "Done" | [DEFINITION-OF-DONE.md](./04-fase-backlog/DEFINITION-OF-DONE.md) |
| Board Kanban | Estado actual del sprint | [Board.md](./planning/Board.md) |
| ADR-001 | Decisiones de stack | [ADR-001-stack-tecnologico.md](./97-adr/ADR-001-stack-tecnologico.md) |
---
## Estadisticas de Documentacion
| Tipo | Cantidad | Estado |
|------|----------|--------|
| Vision/Arquitectura | 3 | Draft |
| DoR/DoD | 2 | Approved |
| ADRs | 1 | Accepted |
| EPICs | 0 | Pendiente |
| User Stories | 0 | Pendiente |
| Planning | 2 | Activo |
| **Total docs** | **8** | - |
---
## EPICs del Proyecto
| ID | Nombre | Fase | Estado | Docs |
|----|--------|------|--------|------|
| BA-001 | Fundamentos | 01-alcance-inicial | Planificada | 0 |
| BA-002 | Ingestion de Datos | 01-alcance-inicial | Backlog | 0 |
| BA-003 | Analytics Engine | 01-alcance-inicial | Backlog | 0 |
| BA-004 | Predicciones ML | 02-robustecimiento | Backlog | 0 |
| BA-005 | Reportes y Dashboard | 02-robustecimiento | Backlog | 0 |
---
## Referencias Externas
| Documento | Ubicacion |
|-----------|-----------|
| AGENTS.md | [../AGENTS.md](../AGENTS.md) |
| README proyecto | [../README.md](../README.md) |
| INVENTARIO.yml | [../INVENTARIO.yml](../INVENTARIO.yml) |
| Orchestration | [../orchestration/](../orchestration/) |
---
## Proximos Pasos
1. [ ] Crear estructura EPIC BA-001-fundamentos
2. [ ] Documentar RFs y US de autenticacion
3. [ ] Crear inventarios de backend/frontend
4. [ ] Agregar guias de desarrollo
5. [ ] Crear cheatsheets
---
**Generado:** 2026-01-04
**Sistema:** NEXUS v3.4 + SIMCO
**Mantenedor:** @Doc-Agent

112
docs/planning/Board.md Normal file
View File

@ -0,0 +1,112 @@
---
id: "BOARD-BA"
title: "Tablero Kanban - Betting Analytics"
type: "Planning"
project: "betting-analytics"
sprint: "Sprint-0"
updated_date: "2026-01-04"
---
# Tablero Kanban - Betting Analytics
**Sprint Actual:** Sprint-0 (Planificacion)
**Fecha:** 2026-01-04
**Velocidad Target:** 30 SP
---
## Resumen del Sprint
| Metrica | Valor |
|---------|-------|
| **SP Planificados** | 0 |
| **SP Completados** | 0 |
| **SP En Progreso** | 0 |
| **Bugs Abiertos** | 0 |
| **Progreso** | 0% |
---
## Tablero
### Backlog
| ID | Titulo | SP | Prioridad | Asignado |
|----|--------|-----|-----------|----------|
| US-BA-001 | Configurar autenticacion JWT | 8 | Alta | - |
| US-BA-002 | Crear modulo de ingestion de datos | 13 | Alta | - |
| US-BA-003 | Dashboard principal | 8 | Media | - |
### Por Hacer (Sprint-1)
| ID | Titulo | SP | Prioridad | Asignado |
|----|--------|-----|-----------|----------|
| - | - | - | - | - |
### En Progreso
| ID | Titulo | SP | Inicio | Asignado |
|----|--------|-----|--------|----------|
| - | - | - | - | - |
### Bloqueado
| ID | Titulo | SP | Bloqueador | Asignado |
|----|--------|-----|------------|----------|
| - | - | - | - | - |
### En Revision
| ID | Titulo | SP | Revisor | Asignado |
|----|--------|-----|---------|----------|
| - | - | - | - | - |
### Hecho (Sprint-0)
| ID | Titulo | SP | Completado | Asignado |
|----|--------|-----|------------|----------|
| TASK-SETUP-001 | Crear estructura documentacion | - | 2026-01-04 | @Doc-Agent |
---
## Bugs Activos
| ID | Titulo | Severidad | Estado | Asignado |
|----|--------|-----------|--------|----------|
| - | - | - | - | - |
---
## Notas del Sprint
### Sprint-0 (Planificacion)
- **Inicio:** 2026-01-04
- **Objetivo:** Establecer documentacion base y estructura del proyecto
- **Notas:**
- Proyecto en fase de planificacion
- Estructura NestJS base implementada
- Modulo auth placeholder creado
- Pendiente definir modulos de negocio
---
## Historico de Sprints
| Sprint | Fecha | SP Plan | SP Real | Notas |
|--------|-------|---------|---------|-------|
| Sprint-0 | 2026-01-04 | 0 | 0 | Planificacion inicial |
---
## Referencias
- **AGENTS.md:** [../AGENTS.md](../../AGENTS.md)
- **Configuracion:** [config.yml](./config.yml)
- **DoR:** [../04-fase-backlog/DEFINITION-OF-READY.md](../04-fase-backlog/DEFINITION-OF-READY.md)
- **DoD:** [../04-fase-backlog/DEFINITION-OF-DONE.md](../04-fase-backlog/DEFINITION-OF-DONE.md)
---
**Actualizado:** 2026-01-04
**Mantenedor:** @Scrum-Agent

56
docs/planning/_MAP.md Normal file
View File

@ -0,0 +1,56 @@
---
id: "MAP-PLANNING"
title: "Mapa de Navegacion - Planning"
type: "Navigation"
folder: "planning"
updated_date: "2026-01-04"
---
# _MAP: planning
**Carpeta:** Planificacion Activa
**Proyecto:** Betting Analytics
**Actualizado:** 2026-01-04
---
## Proposito
Esta carpeta contiene la infraestructura SCRUM para la planificacion y tracking del proyecto, incluyendo el tablero Kanban, configuracion y archivos de tareas/bugs activos.
---
## Contenido
| Archivo | Titulo | Descripcion |
|---------|--------|-------------|
| [Board.md](./Board.md) | Tablero Kanban | Estado actual del sprint |
| [config.yml](./config.yml) | Configuracion SCRUM | Parametros del proyecto |
| tasks/ | Tareas activas | Archivos TASK-BA-XXX.md |
| bugs/ | Bugs activos | Archivos BUG-BA-XXX.md |
---
## Estadisticas Sprint-0
| Metrica | Valor |
|---------|-------|
| SP Planificados | 0 |
| SP Completados | 0 |
| Tareas Activas | 0 |
| Bugs Abiertos | 0 |
---
## Referencias
- **Nivel superior:** [../README.md](../README.md)
- **Mapa principal:** [../_MAP.md](../_MAP.md)
- **DoR:** [../04-fase-backlog/DEFINITION-OF-READY.md](../04-fase-backlog/DEFINITION-OF-READY.md)
- **DoD:** [../04-fase-backlog/DEFINITION-OF-DONE.md](../04-fase-backlog/DEFINITION-OF-DONE.md)
- **AGENTS:** [../../AGENTS.md](../../AGENTS.md)
---
**Generado:** 2026-01-04
**Mantenedor:** @Scrum-Agent

228
docs/planning/config.yml Normal file
View File

@ -0,0 +1,228 @@
# ==============================================================================
# CONFIGURACION SCRUM - BETTING ANALYTICS
# ==============================================================================
# Configuracion del proyecto para agentes IA
# Sistema: NEXUS v3.4 + SIMCO + SCRUM
# ==============================================================================
project:
name: "Betting Analytics"
code: "BA"
version: "0.1.0"
status: "planning"
created_date: "2025-12-05"
updated_date: "2026-01-04"
# Estados validos por tipo de documento
states:
user_story:
- "Backlog"
- "To Do"
- "In Progress"
- "In Review"
- "Done"
task:
- "To Do"
- "In Progress"
- "Blocked"
- "Done"
bug:
- "Open"
- "In Progress"
- "Fixed"
- "Done"
- "Won't Fix"
requirement:
- "Draft"
- "Approved"
- "Implemented"
- "Done"
# Prioridades y SLAs
priorities:
- id: "P0"
name: "Critico"
sla_hours: 4
description: "Bloquea produccion"
- id: "P1"
name: "Alto"
sla_hours: 24
description: "Impacta funcionalidad core"
- id: "P2"
name: "Medio"
sla_hours: 72
description: "Funcionalidad importante"
- id: "P3"
name: "Bajo"
sla_hours: 168
description: "Mejora o feature menor"
# Nomenclatura del proyecto
naming:
project_prefix: "BA"
epic_prefix: "BA"
user_story: "US-BA"
task: "TASK-BA"
bug: "BUG-BA"
requirement: "RF-BA"
specification: "ET-BA"
adr: "ADR"
# Categorias de User Stories
us_categories:
- prefix: "AUTH"
epic: "BA-001"
description: "Autenticacion y Seguridad"
- prefix: "DATA"
epic: "BA-002"
description: "Ingestion de Datos"
- prefix: "AN"
epic: "BA-003"
description: "Analytics"
- prefix: "PRED"
epic: "BA-004"
description: "Predicciones ML"
- prefix: "REP"
epic: "BA-005"
description: "Reportes"
# EPICs del proyecto
epics:
- id: "BA-001"
name: "Fundamentos"
phase: "01-fase-alcance-inicial"
status: "In Progress"
description: "Configuracion base, autenticacion, estructura"
- id: "BA-002"
name: "Ingestion de Datos"
phase: "01-fase-alcance-inicial"
status: "Backlog"
description: "Recoleccion y procesamiento de datos"
- id: "BA-003"
name: "Analytics Engine"
phase: "01-fase-alcance-inicial"
status: "Backlog"
description: "Motor de analisis estadistico"
- id: "BA-004"
name: "Predicciones ML"
phase: "02-fase-robustecimiento"
status: "Backlog"
description: "Modelos de machine learning"
- id: "BA-005"
name: "Reportes y Dashboard"
phase: "02-fase-robustecimiento"
status: "Backlog"
description: "Visualizacion y reportes"
# Configuracion de Sprint
sprint:
duration_days: 10
velocity_target: 30
current_sprint: 0
sprint_name: "Sprint-0"
start_date: "2026-01-04"
end_date: "2026-01-14"
# Agentes disponibles
agents:
- id: "@Backend-Agent"
specialization: "NestJS, TypeORM, APIs REST"
availability: "full"
- id: "@Frontend-Agent"
specialization: "React, TypeScript, Vite"
availability: "full"
- id: "@ML-Agent"
specialization: "Python, FastAPI, ML Models"
availability: "partial"
- id: "@DB-Agent"
specialization: "PostgreSQL, TypeORM, Migrations"
availability: "full"
- id: "@DevOps-Agent"
specialization: "Docker, CI/CD, Infra"
availability: "partial"
# Campos requeridos por tipo
required_fields:
user_story:
- "id"
- "title"
- "type"
- "status"
- "priority"
- "epic"
- "story_points"
- "created_date"
task:
- "id"
- "title"
- "type"
- "status"
- "priority"
- "created_date"
bug:
- "id"
- "title"
- "type"
- "status"
- "severity"
- "affected_module"
- "steps_to_reproduce"
- "created_date"
requirement:
- "id"
- "title"
- "type"
- "status"
- "priority"
- "module"
- "epic"
- "created_date"
# Metricas del proyecto
metrics:
total_epics: 5
total_user_stories: 0
total_requirements: 0
total_specifications: 0
stories_with_yaml: 0
compliance_target: 100
coverage_target: 80
# Stack tecnologico
stack:
backend:
framework: "NestJS"
language: "TypeScript"
orm: "TypeORM"
runtime: "Node.js 20"
frontend:
framework: "React"
language: "TypeScript"
bundler: "Vite"
ui: "TBD"
database:
primary: "PostgreSQL"
cache: "Redis (planned)"
ml:
framework: "FastAPI"
language: "Python 3.11"
ml_libs: "scikit-learn, pandas"
infrastructure:
containerization: "Docker"
orchestration: "Docker Compose"
ci_cd: "GitHub Actions (planned)"
# Rutas importantes
paths:
docs: "docs/"
planning: "docs/planning/"
board: "docs/planning/Board.md"
agents: "AGENTS.md"
backend: "apps/backend/"
frontend: "apps/frontend/"
ml: "apps/ml/"
orchestration: "orchestration/"
# ==============================================================================
# FIN DE CONFIGURACION
# ==============================================================================

2
orchestration/00-guidelines/CONTEXTO-PROYECTO.md
View File

@ -129,7 +129,7 @@ Este proyecto hereda directivas de:
| Recurso | Path | | Recurso | Path |
|---------|------| |---------|------|
| Core orchestration | `/home/isem/workspace-v1/core/orchestration/` | | Core orchestration | `/home/isem/workspace-v1/core/orchestration/` |
| Catálogo global | `/home/isem/workspace-v1/core/catalog/` | | Catálogo global | `/home/isem/workspace-v1/shared/catalog/` |
--- ---
*Contexto del proyecto - Sistema NEXUS + SIMCO v2.2.0* *Contexto del proyecto - Sistema NEXUS + SIMCO v2.2.0*

2
orchestration/00-guidelines/HERENCIA-DIRECTIVAS.md
View File

@ -83,7 +83,7 @@ Este proyecto utiliza las siguientes funcionalidades del catálogo core:
|---------------|-------------------| |---------------|-------------------|
| *(Por definir según necesidades del proyecto)* | - | | *(Por definir según necesidades del proyecto)* | - |
**Path catálogo:** `~/workspace/core/catalog/` **Path catálogo:** `~/workspace/shared/catalog/`
## Uso para Subagentes ## Uso para Subagentes

158
orchestration/CONTEXT-MAP.yml Normal file
View File

@ -0,0 +1,158 @@
# CONTEXT-MAP: BETTING-ANALYTICS
# Sistema: SIMCO - NEXUS v4.0
# Propósito: Mapear contexto automático por nivel y tarea
# Versión: 1.0.0
# Fecha: 2026-01-04
metadata:
proyecto: "betting-analytics"
nivel: "STANDALONE"
version: "1.0.0"
ultima_actualizacion: "2026-01-04"
workspace_root: "/home/isem/workspace-v1"
project_root: "/home/isem/workspace-v1/projects/betting-analytics"
# ═══════════════════════════════════════════════════════════════════════════════
# VARIABLES DEL PROYECTO (PRE-RESUELTAS)
# ═══════════════════════════════════════════════════════════════════════════════
variables:
# Identificación
PROJECT: "betting-analytics"
PROJECT_NAME: "BETTING-ANALYTICS"
PROJECT_LEVEL: "STANDALONE"
# Paths principales
APPS_ROOT: "/home/isem/workspace-v1/projects/betting-analytics/apps"
DOCS_ROOT: "/home/isem/workspace-v1/projects/betting-analytics/docs"
ORCHESTRATION_PATH: "/home/isem/workspace-v1/projects/betting-analytics/orchestration"
# ═══════════════════════════════════════════════════════════════════════════════
# ALIASES RESUELTOS
# ═══════════════════════════════════════════════════════════════════════════════
aliases:
# Directivas globales
"@SIMCO": "/home/isem/workspace-v1/orchestration/directivas/simco"
"@PRINCIPIOS": "/home/isem/workspace-v1/orchestration/directivas/principios"
"@PERFILES": "/home/isem/workspace-v1/orchestration/agents/perfiles"
"@CATALOG": "/home/isem/workspace-v1/shared/catalog"
# Proyecto específico
"@APPS": "/home/isem/workspace-v1/projects/betting-analytics/apps"
"@DOCS": "/home/isem/workspace-v1/projects/betting-analytics/docs"
# Inventarios
"@INVENTORY": "/home/isem/workspace-v1/projects/betting-analytics/orchestration/inventarios"
# ═══════════════════════════════════════════════════════════════════════════════
# CONTEXTO POR NIVEL
# ═══════════════════════════════════════════════════════════════════════════════
contexto_por_nivel:
L0_sistema:
descripcion: "Principios fundamentales y perfil de agente"
tokens_estimados: 4500
obligatorio: true
archivos:
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-CAPVED.md"
proposito: "Ciclo de vida de tareas"
tokens: 800
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md"
proposito: "Documentación antes de código"
tokens: 500
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md"
proposito: "Verificar catálogo antes de crear"
tokens: 600
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md"
proposito: "Build/lint deben pasar"
tokens: 600
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md"
proposito: "Límites de contexto"
tokens: 500
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md"
proposito: "Preguntar si falta información"
tokens: 500
- path: "/home/isem/workspace-v1/orchestration/referencias/ALIASES.yml"
proposito: "Resolución de @ALIAS"
tokens: 400
L1_proyecto:
descripcion: "Contexto específico de BETTING-ANALYTICS"
tokens_estimados: 3000
obligatorio: true
archivos:
- path: "/home/isem/workspace-v1/projects/betting-analytics/orchestration/00-guidelines/CONTEXTO-PROYECTO.md"
proposito: "Variables y configuración del proyecto"
tokens: 1500
- path: "/home/isem/workspace-v1/projects/betting-analytics/orchestration/PROXIMA-ACCION.md"
proposito: "Estado actual y siguiente paso"
tokens: 500
L2_operacion:
descripcion: "SIMCO específicos según operación y dominio"
tokens_estimados: 2500
archivos_por_operacion:
CREAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-CREAR.md"
MODIFICAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-MODIFICAR.md"
VALIDAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-VALIDAR.md"
DELEGAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-DELEGACION.md"
L3_tarea:
descripcion: "Contexto específico de la tarea"
tokens_max: 8000
dinamico: true
# ═══════════════════════════════════════════════════════════════════════════════
# INFORMACIÓN ESPECÍFICA DEL PROYECTO
# ═══════════════════════════════════════════════════════════════════════════════
info_proyecto:
tipo: "Plataforma de Análisis de Apuestas Deportivas"
estado: "En desarrollo inicial"
version: "0.1"
stack:
apps: "Aplicaciones de análisis"
docs: "Documentación del proyecto"
# ═══════════════════════════════════════════════════════════════════════════════
# VALIDACIÓN DE TOKENS
# ═══════════════════════════════════════════════════════════════════════════════
validacion_tokens:
limite_absoluto: 25000
limite_seguro: 18000
limite_alerta: 20000
presupuesto:
L0_sistema: 4500
L1_proyecto: 3000
L2_operacion: 2500
L3_tarea_max: 8000
total_base: 10000
disponible_tarea: 8000
# ═══════════════════════════════════════════════════════════════════════════════
# HERENCIA
# ═══════════════════════════════════════════════════════════════════════════════
herencia:
tipo: "STANDALONE"
hereda_de:
- "/home/isem/workspace-v1/orchestration/"
# ═══════════════════════════════════════════════════════════════════════════════
# BÚSQUEDA DE HISTÓRICO
# ═══════════════════════════════════════════════════════════════════════════════
busqueda_historico:
habilitado: true
ubicaciones:
- "/home/isem/workspace-v1/projects/betting-analytics/orchestration/trazas/"
- "/home/isem/workspace-v1/orchestration/errores/REGISTRO-ERRORES.yml"
- "/home/isem/workspace-v1/shared/knowledge-base/lessons-learned/"

72
orchestration/PROJECT-STATUS.md Normal file
View File

@ -0,0 +1,72 @@
# PROJECT STATUS - Betting Analytics
**Fecha:** 2026-01-07
**Estado:** Planificacion
**Fase:** Pre-Desarrollo
---
## Resumen Ejecutivo
| Aspecto | Estado | Notas |
|---------|--------|-------|
| Vision | Pendiente | Por definir |
| Arquitectura | Pendiente | Por definir |
| Database | Pendiente | - |
| Backend | Pendiente | - |
| Frontend | Pendiente | - |
| ML/Analytics | Pendiente | Core del proyecto |
---
## Descripcion
Proyecto de analitica para apuestas deportivas. Requiere definicion de alcance y requerimientos iniciales.
---
## Progreso
| Fase | Estado | Notas |
|------|--------|-------|
| Planificacion | Pendiente | Alcance por definir |
| Documentacion | Pendiente | - |
| Desarrollo | Pendiente | - |
| Testing | Pendiente | - |
| Deploy | Pendiente | - |
---
## Proximas Acciones
1. Definir vision y alcance del proyecto
2. Documentar requerimientos funcionales
3. Disenar arquitectura tecnica
4. Crear estructura base de proyecto
---
## Stack Propuesto
| Capa | Tecnologia |
|------|------------|
| Backend | Python/FastAPI o NestJS |
| Frontend | React + Vite |
| Database | PostgreSQL + TimescaleDB |
| ML | Python + scikit-learn/XGBoost |
| Analytics | Metabase/Grafana |
---
## Riesgos
| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Regulaciones legales | Alta | Alto | Consulta legal |
| Calidad de datos | Media | Alto | Validacion de fuentes |
| Complejidad modelos | Media | Medio | MVP simple |
---
**Ultima actualizacion:** 2026-01-07
**Actualizado por:** Orquestador

194
orchestration/environment/ENVIRONMENT-INVENTORY.yml Normal file
View File

@ -0,0 +1,194 @@
# =============================================================================
# ENVIRONMENT-INVENTORY.yml - BETTING-ANALYTICS
# =============================================================================
# Inventario de Entorno de Desarrollo
# Generado por: @PERFIL_DEVENV
# Estado: RESERVADO (pendiente de implementacion)
# =============================================================================
version: "1.0.0"
fecha_creacion: "2026-01-04"
fecha_actualizacion: "2026-01-04"
responsable: "@PERFIL_DEVENV"
estado: "RESERVADO"
# -----------------------------------------------------------------------------
# IDENTIFICACION DEL PROYECTO
# -----------------------------------------------------------------------------
proyecto:
nombre: "Betting Analytics"
alias: "betting"
nivel: "NIVEL_2A"
tipo: "standalone"
estado: "reservado"
descripcion: "Plataforma de analitica de apuestas deportivas"
# -----------------------------------------------------------------------------
# HERRAMIENTAS Y RUNTIME (PLANIFICADO)
# -----------------------------------------------------------------------------
herramientas:
runtime:
node:
version: "20.x"
requerido: true
notas: "Para backend NestJS y frontend React"
python:
version: "3.11"
requerido: true
notas: "Para servicios ML"
package_managers:
npm:
version: "10.x"
requerido: true
pip:
version: "23.x"
requerido: true
build_tools:
- nombre: "Vite"
version: "5.x"
uso: "Frontend build"
- nombre: "TypeScript"
version: "5.x"
uso: "Compilacion"
- nombre: "NestJS CLI"
version: "10.x"
uso: "Backend build"
# -----------------------------------------------------------------------------
# SERVICIOS Y PUERTOS (RESERVADOS)
# -----------------------------------------------------------------------------
servicios:
frontend:
nombre: "betting-frontend"
framework: "React"
version: "18.x"
puerto: 3090
ubicacion: "apps/frontend/"
url_local: "http://localhost:3090"
estado: "reservado"
backend:
nombre: "betting-backend"
framework: "NestJS"
version: "10.x"
puerto: 3091
ubicacion: "apps/backend/"
url_local: "http://localhost:3091"
api_prefix: "/api/v1"
estado: "reservado"
ml_service:
nombre: "betting-ml"
framework: "FastAPI"
puerto: 3092
ubicacion: "apps/ml-service/"
url_local: "http://localhost:3092"
estado: "reservado"
# -----------------------------------------------------------------------------
# BASE DE DATOS (RESERVADO)
# -----------------------------------------------------------------------------
base_de_datos:
principal:
engine: "PostgreSQL"
version: "15"
host: "localhost"
puerto: 5438
ambientes:
development:
nombre: "betting_development"
usuario: "betting_dev"
password_ref: "DB_PASSWORD en .env"
test:
nombre: "betting_test"
usuario: "betting_dev"
password_ref: "DB_PASSWORD en .env"
schemas:
- nombre: "public"
descripcion: "Schema principal"
conexion_ejemplo: "postgresql://betting_dev:{password}@localhost:5438/betting_development"
estado: "reservado - BD no creada aun"
redis:
host: "localhost"
puerto: 6385
uso: "cache, sessions"
estado: "reservado"
# -----------------------------------------------------------------------------
# VARIABLES DE ENTORNO (TEMPLATE)
# -----------------------------------------------------------------------------
variables_entorno:
archivo_ejemplo: ".env.example"
estado: "pendiente de crear"
variables:
- nombre: "NODE_ENV"
descripcion: "Ambiente de ejecucion"
requerido: true
ejemplo: "development"
- nombre: "PORT"
descripcion: "Puerto del servidor backend"
requerido: true
ejemplo: "3091"
- nombre: "DATABASE_URL"
descripcion: "Connection string de PostgreSQL"
requerido: true
ejemplo: "postgresql://betting_dev:password@localhost:5438/betting_development"
- nombre: "REDIS_URL"
descripcion: "Connection string de Redis"
requerido: true
ejemplo: "redis://localhost:6385"
- nombre: "JWT_SECRET"
descripcion: "Secreto para JWT"
requerido: true
sensible: true
# -----------------------------------------------------------------------------
# NOTAS DE IMPLEMENTACION
# -----------------------------------------------------------------------------
notas_implementacion: |
## Estado: RESERVADO
Este proyecto tiene puertos y recursos reservados pero aun no esta implementado.
### Recursos Reservados:
- Puertos: 3090-3092
- PostgreSQL: puerto 5438
- Redis: puerto 6385
- BD: betting_development / betting_dev
### Pasos para Activar:
1. Crear estructura de proyecto
2. Crear BD y usuario
3. Configurar .env.example
4. Actualizar estado a "desarrollo"
# -----------------------------------------------------------------------------
# REFERENCIAS
# -----------------------------------------------------------------------------
referencias:
perfil_devenv: "orchestration/agents/perfiles/PERFIL-DEVENV.md"
inventario_master: "orchestration/inventarios/DEVENV-MASTER-INVENTORY.yml"
inventario_puertos: "orchestration/inventarios/DEVENV-PORTS-INVENTORY.yml"
# =============================================================================
# FIN DE INVENTARIO
# =============================================================================