# 🏗️ ARQUITECTURA DEL SISTEMA - Osorno Runners

## 📐 Diagrama de Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                    HUGGINGFACE SPACES                           │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                                                             │  │
│  │  ┌─────────────┐         ┌──────────────┐                │  │
│  │  │   Gradio    │◄────────┤   app.py     │                │  │
│  │  │  Framework  │         │   (Python)   │                │  │
│  │  │             │         │              │                │  │
│  │  │  ┌───────┐  │         │  ┌────────┐  │                │  │
│  │  │  │Server │  │         │  │ APIs   │  │                │  │
│  │  │  │Port   │  │         │  │ REST   │  │                │  │
│  │  │  │ 7860  │  │         │  └────────┘  │                │  │
│  │  └─────┬─────┘  │         └──────┬───────┘                │  │
│  │        │        │                │                        │  │
│  │        ▼        │                ▼                        │  │
│  │  ┌──────────────┴────────────────────────────┐           │  │
│  │  │         index.html (Frontend)             │           │  │
│  │  │  ┌──────────────────────────────────────┐ │           │  │
│  │  │  │  HTML5 + CSS3 + JavaScript           │ │           │  │
│  │  │  │  - Login Form                        │ │           │  │
│  │  │  │  - Dashboard                         │ │           │  │
│  │  │  │  - Training Plan Creator             │ │           │  │
│  │  │  │  - Plan List                         │ │           │  │
│  │  │  │  - PDF Export (jsPDF)                │ │           │  │
│  │  │  └──────────────────────────────────────┘ │           │  │
│  │  └───────────────────────────────────────────┘           │  │
│  │                        │                                  │  │
│  │                        ▼                                  │  │
│  │  ┌─────────────────────────────────────────┐             │  │
│  │  │      SQLite Database (Persistent)       │             │  │
│  │  │                                           │             │  │
│  │  │  ┌────────────────┐  ┌────────────────┐ │             │  │
│  │  │  │  Tabla: users  │  │ Tabla: planes  │ │             │  │
│  │  │  │  - username    │  │ - id           │ │             │  │
│  │  │  │  - password    │  │ - plan_data    │ │             │  │
│  │  │  │  - role        │  │ - created_at   │ │             │  │
│  │  │  │  - name        │  │ - created_by   │ │             │  │
│  │  │  └────────────────┘  │ - athlete_name │ │             │  │
│  │  │                      │ - distance     │ │             │  │
│  │  │                      │ - race_date    │ │             │  │
│  │  │                      └────────────────┘ │             │  │
│  │  │                                           │             │  │
│  │  │  Archivo: osorno_runners.db              │             │  │
│  │  └─────────────────────────────────────────┘             │  │
│  │                                                             │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  URL: https://huggingface.co/spaces/USUARIO/osorno-runners     │
└─────────────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS
                            ▼
                   ┌──────────────────┐
                   │   NAVEGADOR      │
                   │   DEL USUARIO    │
                   │                  │
                   │  Chrome/Firefox  │
                   │  Safari/Edge     │
                   └──────────────────┘
```

---

## 🔄 Flujo de Datos

### 1️⃣ **Login**
```
Usuario ingresa credenciales
       │
       ▼
index.html (Frontend)
       │
       │ POST /api/login
       ▼
app.py (Backend)
       │
       │ authenticate_user()
       ▼
SQLite (users table)
       │
       │ Return user data
       ▼
Frontend muestra dashboard
```

### 2️⃣ **Crear Plan**
```
Usuario completa formulario
       │
       ▼
index.html valida datos
       │
       │ Genera plan con algoritmos JS
       ▼
Cálculos de:
  - Duración (calculateWeeks)
  - Kilometraje (getBaseKm)
  - Zonas FC (calculateHRZones)
  - Sesiones (generateWeekSessions)
       │
       │ POST /api/save_plan
       ▼
app.py (Backend)
       │
       │ save_plan_to_db()
       ▼
SQLite (planes table)
       │
       │ Return plan ID
       ▼
Frontend muestra confirmación
```

### 3️⃣ **Ver Planes**
```
Usuario navega a "Ver Planes"
       │
       │ GET /api/get_plans
       ▼
app.py (Backend)
       │
       │ get_all_plans(username, role)
       ▼
SQLite query según permisos:
  - User: WHERE created_by = username
  - Admin: SELECT * FROM planes
       │
       │ Return JSON con planes
       ▼
Frontend renderiza lista de planes
```

### 4️⃣ **Exportar PDF**
```
Usuario click en "Exportar PDF"
       │
       ▼
Frontend (jsPDF library)
       │
       │ Lee datos del plan
       │ Genera PDF en el navegador
       ▼
Descarga automática del PDF
(No involucra backend)
```

### 5️⃣ **Eliminar Plan** (Solo Admin)
```
Admin click en "Eliminar"
       │
       │ Confirmación
       ▼
index.html
       │
       │ DELETE /api/delete_plan
       ▼
app.py (Backend)
       │
       │ delete_plan_from_db(plan_id)
       ▼
SQLite elimina registro
       │
       │ Return success
       ▼
Frontend recarga lista de planes
```

---

## 🔐 Sistema de Autenticación

```
┌────────────────────────────────────────┐
│         authenticate_user()            │
│                                        │
│  Input: username, password             │
│         │                              │
│         ▼                              │
│  Query: SELECT role, name              │
│         FROM users                     │
│         WHERE username = ? AND         │
│               password = ?             │
│         │                              │
│         ▼                              │
│  ┌─────────┬──────────┐               │
│  │ Found?  │          │               │
│  ▼ YES     ▼ NO       │               │
│  Return:   Return:    │               │
│  {         None       │               │
│    username,          │               │
│    role,              │               │
│    name               │               │
│  }                    │               │
└────────────────────────────────────────┘
```

---

## 💾 Modelo de Datos

### Tabla: **users**
```sql
CREATE TABLE users (
    username TEXT PRIMARY KEY,  -- 'USER', 'ADMIN'
    password TEXT NOT NULL,     -- '123' (cambiar en prod)
    role TEXT NOT NULL,         -- 'user', 'admin'
    name TEXT NOT NULL          -- 'Usuario', 'Administrador'
);
```

**Ejemplo de datos:**
```
┌──────────┬──────────┬───────┬─────────────────┐
│ username │ password │ role  │ name            │
├──────────┼──────────┼───────┼─────────────────┤
│ USER     │ 123      │ user  │ Usuario         │
│ ADMIN    │ 123      │ admin │ Administrador   │
└──────────┴──────────┴───────┴─────────────────┘
```

### Tabla: **planes**
```sql
CREATE TABLE planes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    plan_data TEXT NOT NULL,           -- JSON del plan completo
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by TEXT NOT NULL,          -- Username del creador
    athlete_name TEXT NOT NULL,        -- Nombre del atleta
    distance TEXT NOT NULL,            -- '5K', '10K', '21K', '42K'
    race_date TEXT NOT NULL            -- Fecha de la carrera
);
```

**Ejemplo de plan_data (JSON):**
```json
{
  "id": 1,
  "userData": {
    "name": "Rodrigo Garcés",
    "age": 40,
    "experience": "intermedio",
    "weight": 75,
    "height": 175,
    "imc": 24.5,
    "hrMax": 180,
    "hrRest": 60,
    "vo2max": 45,
    "distance": "42K",
    "targetPace": "4:30",
    "raceDate": "2025-04-20",
    "trainingDays": ["lunes", "miércoles", "viernes", "domingo"]
  },
  "totalWeeks": 20,
  "weeklyPlans": [
    {
      "week": 1,
      "period": "basico",
      "sessions": [...],
      "totalKm": 35
    },
    ...
  ]
}
```

---

## 🔄 Ciclo de Vida de un Plan

```
1. CREACIÓN
   ├─ Usuario completa formulario
   ├─ JS valida datos
   ├─ Algoritmos generan plan
   ├─ POST a /api/save_plan
   └─ Guarda en SQLite

2. ALMACENAMIENTO
   ├─ plan_data como JSON TEXT
   ├─ Metadata en columnas separadas
   └─ Timestamp automático

3. RECUPERACIÓN
   ├─ GET a /api/get_plans
   ├─ Query según role
   ├─ Parse JSON
   └─ Return array de planes

4. VISUALIZACIÓN
   ├─ Frontend recibe JSON
   ├─ Renderiza HTML dinámico
   └─ Muestra detalles

5. EXPORTACIÓN
   ├─ jsPDF en cliente
   ├─ Sin backend
   └─ PDF descargado

6. ELIMINACIÓN (Admin)
   ├─ DELETE a /api/delete_plan
   ├─ Remove de SQLite
   └─ Refresh lista
```

---

## 🌐 Endpoints de la API

### **POST /api/login**
```python
Request:  {"username": "USER", "password": "123"}
Response: {"success": true, "user": {...}}
```

### **POST /api/save_plan**
```python
Request:  {"plan": "{...}", "username": "ADMIN"}
Response: {"success": true, "id": 1}
```

### **GET /api/get_plans**
```python
Request:  {"username": "USER", "role": "user"}
Response: {"success": true, "plans": [...]}
```

### **DELETE /api/delete_plan**
```python
Request:  {"plan_id": 1}
Response: {"success": true}
```

---

## 🔧 Stack Tecnológico

### **Frontend**
- HTML5
- CSS3 (Variables CSS, Flexbox, Grid)
- JavaScript (ES6+)
- jsPDF 2.5.1
- Font Awesome 6.4.0

### **Backend**
- Python 3.8+
- Gradio 4.44.0
- SQLite3 (Built-in)

### **Infraestructura**
- HuggingFace Spaces
- CPU basic (2 vCPU, 16 GB RAM)
- 50 GB Storage
- HTTPS automático

---

## 📊 Métricas de Rendimiento

```
Tamaño de archivos:
├─ app.py:           7.3 KB
├─ index.html:      17.0 KB
├─ requirements.txt: 0.015 KB
└─ Total:          ~24.3 KB

Base de datos:
├─ Vacía:            ~20 KB
├─ 10 planes:       ~100 KB
├─ 100 planes:        ~1 MB
└─ Límite HF:        50 GB

Tiempos de respuesta:
├─ Login:           ~100 ms
├─ Crear plan:      ~200 ms
├─ Cargar planes:   ~150 ms
└─ Exportar PDF:     ~1-2 seg (cliente)
```

---

## 🛡️ Seguridad

### Implementado ✅
- Autenticación de usuarios
- Validación de formularios
- Manejo de errores
- Logs de actividad
- Separación de permisos

### Por Implementar 🔒
- Hashing de contraseñas (bcrypt)
- Tokens de sesión (JWT)
- Rate limiting
- Sanitización de inputs
- HTTPS forzado (HF lo hace)

---

## 📈 Escalabilidad

### Límites Actuales
- SQLite: ~140 TB teórico (práctico: GB)
- HuggingFace: 50 GB storage
- Concurrent users: ~100
- Request/min: Ilimitado en HF

### Para Escalar
1. Migrar a PostgreSQL
2. Implementar Redis para cache
3. CDN para assets
4. Load balancing
5. Microservicios

---

**Esta arquitectura es ideal para:**
- ✅ Prototipo rápido
- ✅ MVP (Minimum Viable Product)
- ✅ Equipos pequeños (< 50 usuarios)
- ✅ Presupuesto cero

**Para producción enterprise, considerar:**
- Migrar a AWS/GCP/Azure
- Base de datos dedicada
- Backups automáticos
- Monitoreo 24/7
- CI/CD pipeline