Spaces:

VeuReu
/

compliance

Sleeping

App Files Files Community

compliance / README.md

VeuReu

Upload 2 files

3bfd23a verified 6 months ago

preview code

raw

history blame contribute delete

9.3 kB

metadata

title: veureu-compliance
emoji: 🔐
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false

🔐 Veureu Compliance Service

Microservicio dedicado de cumplimiento normativo para Veureu.

📋 Visión General

Este space de Hugging Face aloja el servicio de compliance que maneja:

🔐 Autenticación OAuth con Google
📋 Registro de consentimientos en AWS QLDB
⛓️ Publicación de digest en Polygon blockchain
📧 Notificaciones por email a validadores
🔍 Verificación de integridad de registros
📊 Dashboard de monitoreo interno
🛡️ Sistema de resiliencia para desconexiones
💾 Persistencia de estado automática
🔄 Recuperación automática tras reinicios

🏗️ Arquitectura

┌─────────────────┐    API calls    ┌──────────────────────┐
│   demo space    │ ───────────────> │  compliance space    │
│  (Streamlit)    │                  │   (FastAPI + UI)     │
│                 │                  │                      │
│ • Vídeos        │                  │ • Google OAuth       │
│ • Detección     │                  │ • AWS QLDB           │
│ • Audio         │                  │ • Polygon Blockchain │
│ • Estadísticas  │                  │ • Email Notifications│
└─────────────────┘                  │ • Dashboard API      │
                                      └──────────────────────┘

🚀 Despliegue

Como Space de Hugging Face

Crear el space:

# En tu cuenta de veureu
huggingface-cli create-space veureu/compliance --sdk streamlit

Subir los archivos:

git clone https://huggingface.co/spaces/veureu/compliance
cd compliance
cp -r ../path/to/compliance/* .
git add .
git commit -m "Initial compliance service"
git push

Configurar variables de entorno:
- Ir a Settings > Variables and secrets
- Añadir las variables de entorno (ver sección abajo)

🔧 Configuración

Variables de Entorno

Para Producción

# Polygon Blockchain
POLYGON_RPC_URL=https://polygon-rpc.com
POLYGON_CHAIN_ID=137
POLYGON_WALLET_PRIVATE_KEY=your_private_key_here
DIGEST_CONTRACT_ADDR=0x1234567890123456789012345678901234567890
DIGEST_CONTRACT_ABI='[{"inputs":[...]}]'

# AWS QLDB
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=your_secret_key
QLDB_LEDGER_NAME=veureu-compliance

# Google OAuth
GOOGLE_CLIENT_ID=123456789-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

# Email SMTP
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=validators@veureu.cat
SMTP_PASSWORD=your_app_password

Para Desarrollo/Simulación

# Mínimas para funcionamiento básico
# (el sistema usará valores simulados)

📡 API Endpoints

🔐 Autenticación

POST /api/auth/validate
{
  "token": "jwt_token_here"
}
→ { "email": "user@example.com", "name": "User", "verified": true }

POST /api/auth/login-url  
{
  "callback_url": "https://veureu-demo.hf.space"
}
→ { "login_url": "https://accounts.google.com/..." }

POST /api/auth/logout
{
  "token": "jwt_token_here"  
}
→ { "success": true }

📋 Cumplimiento (QLDB)

POST /api/compliance/record-consent
{
  "user_info": {"email": "user@example.com", "name": "User"},
  "video_info": {"name": "video.mp4", "size": 1024000},
  "consent_data": {"rights": true, "biometric": true, ...}
}
→ { "document_id": "doc_1699123456_abc123" }

POST /api/compliance/send-validation
{
  "document_id": "doc_1699123456_abc123",
  "user_email": "user@example.com",
  "video_title": "Mi video",
  ...
}
→ { "success": true }

GET /api/compliance/stats
→ { "total_documents": 1247, "pending_validation": 23, ... }

⛓️ Blockchain (Polygon)

POST /api/blockchain/publish-digest
{
  "period": "2025-11"
}
→ { "transaction_hash": "0xabcdef123456..." }

GET /api/blockchain/digests
→ { "digests": [{ "period": "2025-11", "transaction_hash": "...", ... }] }

POST /api/blockchain/verify-digest
{
  "period": "2025-11",
  "expected_hash": "abcdef123456..."
}
→ { "valid": true }

🛡️ Resiliencia y Recuperación

Manejo de Desconexiones Hugging Face

El servicio está diseñado para manejar desconexiones gracefully:

🔄 Hugging Face desconecta el space
    ↓
💾 Estado persistente guardado en /tmp/compliance_state.json
    ↓
📋 Datos seguros en AWS QLDB (externo)
    ↓
⛓️ Registros inmutables en Polygon (externo)
    ↓
🔄 Space se reconecta
    ↓
🔍 Sistema detecta reinicio
    ↓
🛠️ Recuperación automática:
    • Verificar validaciones pendientes
    • Publicar digest pendientes
    • Sincronizar con QLDB
    • Restaurar estado del servicio

Características de Resiliencia

✅ Persistencia de estado: Archivo JSON local con estado completo
✅ Recuperación automática: Detección y corrección de problemas al inicio
✅ Datos externos: QLDB y Polygon como fuente de verdad
✅ Monitoreo continuo: Dashboard con estado de resiliencia
✅ Recuperación manual: Endpoints para forzar recuperación si es necesario

API de Resiliencia

GET /api/recovery/status
→ Estado detallado de recuperación y acciones pendientes

POST /api/recovery/force  
→ Fuerza recuperación completa del servicio

GET /api/health/detailed
→ Health check con todos los componentes

🔄 Modo Simulación vs Producción

Modo Actual: Simulación 🟡

✅ API endpoints funcionales
✅ Estructura completa implementada
✅ Sistema de resiliencia activo
🔄 Conexiones reales comentadas
🔄 Logs simulados
🔄 Datos de prueba

Modo Producción: Real 🟢

Para activar:

Configurar variables de entorno reales
Descomentar código de integración
Instalar dependencias adicionales:
```
pip install web3 boto3 google-auth
```
Reiniciar el space

💰 Costes y Recursos

Space Compliance

Tipo: CPU Basic (24x7)
Coste estimado: $20-30/mes
Uso: API requests, background jobs, dashboard

Space Demo

Tipo: CPU Basic (ondemand)
Coste estimado: $10-20/mes
Uso: Solo cuando usuarios activos

Total: $30-50/mes (vs $50-100 si todo en uno)

🔍 Monitoreo y Logging

Dashboard Interno

El space incluye un dashboard Streamlit con:

Estado del servicio en tiempo real
Configuración de blockchain
Logs de operaciones
Métricas de uso

Logs Estructurados

# Formato de logs
[INFO] Servicio iniciado correctamente
[QLDB] Consentimiento registrado: doc_1699123456_abc123
[POLYGON] Digest publicado: 2025-11 -> 0xabcdef123456...
[EMAIL] Validación enviada para: doc_1699123456_abc123

🧪 Testing y Desarrollo

Testing Local

# Clonar y ejecutar localmente
git clone https://huggingface.co/spaces/veureu/compliance
cd compliance
pip install -r requirements.txt
streamlit run app.py

Probar API

# Health check
curl https://veureu-compliance.hf.space/

# Validar token (simulado)
curl -X POST https://veureu-compliance.hf.space/api/auth/validate \
  -H "Content-Type: application/json" \
  -d '{"token": "sim_token_user123_sim"}'

🔒 Seguridad

Tokens JWT validados correctamente
Conexiones HTTPS obligatorias
Variables de entorno para credenciales
Logs sin datos sensibles
Rate limiting (por implementar)

📈 Escalabilidad

Vertical

Upgrade a CPU Upgrade si aumenta carga
Más memoria para operaciones blockchain
Storage adicional para logs

Horizontal

Multiple instancias con load balancer
Database separada para QLDB local
CDN para assets estáticos

🛠️ Mantenimiento

Actualizaciones

# Actualizar dependencias
pip install -r requirements.txt --upgrade

# Reiniciar servicio (automático en HF Spaces)
# El space se reinicia automáticamente en cada push

Backup

Configuración: En variables de entorno
Logs: En logging del space
Blockchain: Inmutable por naturaleza
QLDB: Backup automático de AWS

📞 Soporte

Issues Comunes

Timeout en API: Aumentar timeout en cliente
Token inválido: Verificar configuración OAuth
Error Polygon: Revisar private key y contract
Email no enviado: Configurar SMTP correctamente

Debugging

# Ver logs del space
# En HF Spaces: Logs tab en el space

# Probar localmente
streamlit run app.py --logger.level debug

🚀 Estado Actual

🟡 Modo Simulación Activo

✅ API funcionando
✅ Dashboard operativo
✅ Estructura completa
🔄 Producción lista para activar

Próximos pasos:

Desplegar en space real
Configurar variables de entorno
Activar integraciones reales
Monitorear funcionamiento

Para soporte técnico o preguntas, contacta con el equipo de Veureu.