claude-peak.md

# Claude Peak Hours Monitor

## Información General

**URL**: https://claudepeak.beepeek.com
**Puerto**: 5035
**Stack**: FastAPI + Jinja2 + ipapi.co (geolocalización)
**Servicio**: `claude-peak.service`
**Path VPS**: `/home/ubuntu/proyectos-cloud/claude-peak/`

## Qué hace

Aplicación web que monitoriza en tiempo real si estás en horas pico de throttling de Claude Code, basándose en tu geolocalización automática.

**Features:**
- 🌍 Geolocalización automática por IP (ipapi.co)
- 🕐 Detección automática de timezone
- ⏱️ Countdown dinámico hasta próximo cambio de estado
- 🔴/🟢 Indicador visual de estado (pico/normal/fin de semana)
- 📊 Comparación hora local vs Pacific Time
- 📱 Diseño responsive y moderno
- ♻️ Auto-refresh cada 10 minutos

## Horas Pico de Claude

**Horario Pacific**: 5:00am - 11:00am PT
**Horario España**: 14:00 - 20:00 (2pm - 8pm)
**Días**: Lunes a Viernes
**Impacto**: Consumo de tokens 2-3x más rápido
**Fines de semana**: Sin restricciones

## Arquitectura

```
/home/ubuntu/proyectos-cloud/claude-peak/
├── app.py                 # FastAPI main
├── templates/
│   └── index.html        # Frontend con countdown JS
├── static/
│   └── style.css         # Diseño gradiente púrpura
├── venv/                 # Virtual environment
├── requirements.txt
└── deploy.sh            # Script de deploy
```

## Tecnologías

- **FastAPI**: Web framework
- **Jinja2**: Template engine
- **ipapi.co**: API geolocalización gratuita (30K req/mes)
- **pytz + zoneinfo**: Timezone handling
- **httpx**: HTTP client async
- **Nginx**: Reverse proxy
- **Certbot**: SSL automático

## Endpoints

- `GET /` - Interfaz web principal
- `GET /api/status` - JSON con estado actual

## Respuesta API `/api/status`

```json
{
  "geo": {
    "timezone": "Europe/Madrid",
    "city": "Valencia",
    "country": "Spain",
    "ip": "1.2.3.4"
  },
  "peak": {
    "is_peak": true,
    "is_weekend": false,
    "pacific_time": "08:30:45",
    "pacific_date": "2026-04-10",
    "user_time": "17:30:45",
    "user_date": "2026-04-10",
    "user_tz": "Europe/Madrid",
    "next_change": {
      "type": "peak_end",
      "message": "Fin horas pico (11am PT)",
      "datetime": "2026-04-10T11:00:00-07:00",
      "seconds": 9015
    }
  }
}
```

## Deploy

```bash
cd /home/ubuntu/proyectos-cloud/claude-peak
bash deploy.sh
```

O manual:

```bash
cd /home/ubuntu/proyectos-cloud/claude-peak
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart claude-peak
```

## Logs

```bash
# Ver logs en tiempo real
sudo journalctl -u claude-peak -f

# Ver últimas 50 líneas
sudo journalctl -u claude-peak -n 50
```

## Configuración DNS

Registro A creado vía cPanel API v2:
- **Dominio**: beepeek.com
- **Subdominio**: claudepeak
- **Tipo**: A
- **Apunta a**: 204.168.170.41
- **TTL**: 300

## SSL

Certificado Let's Encrypt automático con certbot:
- **Cert**: `/etc/letsencrypt/live/claudepeak.beepeek.com/fullchain.pem`
- **Key**: `/etc/letsencrypt/live/claudepeak.beepeek.com/privkey.pem`
- **Expira**: 2026-07-09 (renovación automática)

## Nginx Config

```nginx
server {
    listen 80;
    server_name claudepeak.beepeek.com;
    # Certbot añade redirect 301 a HTTPS automáticamente
}

server {
    listen 443 ssl;
    server_name claudepeak.beepeek.com;

    ssl_certificate /etc/letsencrypt/live/claudepeak.beepeek.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/claudepeak.beepeek.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5035;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## Colores / Branding

- **Background**: Gradiente púrpura (#667eea → #764ba2)
- **Estado PICO**: Gradiente rojo (#ff6b6b → #ee5a6f)
- **Estado NORMAL**: Gradiente verde (#51cf66 → #37b24d)
- **Accent**: Púrpura #667eea
- **Font**: System fonts (-apple-system, BlinkMacSystemFont, Segoe UI...)

## Uso Típico

1. Usuario entra a https://claudepeak.beepeek.com
2. App detecta IP automáticamente
3. Geolocaliza → obtiene timezone
4. Calcula si está en horas pico
5. Muestra estado visual + countdown
6. Auto-refresh cada 10 min o al llegar a 0

## Casos de Uso

- ✅ Planificar sesiones intensivas de Claude Code
- ✅ Evitar throttling trabajando en horas valle
- ✅ Saber cuánto falta para fin de pico
- ✅ Optimizar uso del plan Max/Pro

## Limitaciones

- **ipapi.co**: 30K requests/mes gratis (suficiente para uso personal)
- **Geolocalización**: Por IP, no GPS (menos preciso pero no requiere permisos)
- **Propagación DNS**: Puede tardar 5-15 min en propagarse globalmente
- **Timezone**: Asume que zona horaria del usuario = geolocalización IP

## Troubleshooting

**DNS no resuelve:**
```bash
# Esperar 5-15 minutos para propagación global
# Verificar:
nslookup claudepeak.beepeek.com 8.8.8.8
```

**Servicio no arranca:**
```bash
sudo journalctl -u claude-peak -n 50
# Check puerto 5035 libre:
sudo lsof -i :5035
```

**Geolocalización falla:**
- Fallback automático a Europe/Madrid
- No afecta funcionalidad, solo precisión

## Mejoras Futuras

- [ ] Historial de uso (guardar en SQLite)
- [ ] Notificaciones push cuando cambia estado
- [ ] PWA installable
- [ ] Gráfico de consumo estimado por hora del día
- [ ] Integración con /stats de Claude Code (requiere API key)
- [ ] Multi-idioma (EN/ES)
- [ ] Dark/Light theme toggle

## Creado

**Fecha**: 2026-04-10
**Por**: Fred (Claude Code)
**Razón**: Monitorizar horas pico de throttling de Claude tras investigación exhaustiva que confirmó el throttling real de Anthropic