workspace/projects/gamilit/docs/90-transversal/arquitectura/STORAGE-SYSTEM.md

Sistema de Almacenamiento (Storage)

Schema: storage Propósito: Integración con sistema de almacenamiento de archivos (Storage compatible) Estado: ✅ Implementado Última actualización: 2025-11-08

---

📋 Descripción

El schema storage proporciona tipos y estructuras para la integración con el sistema de almacenamiento de archivos de Storage compatible, utilizado para gestionar archivos multimedia de la plataforma (imágenes, videos, documentos, etc.).

---

🗂️ Objetos del Schema

Enum: buckettype

Archivo: apps/database/ddl/schemas/storage/enums/buckettype.sql

Descripción: Define los tipos de buckets de almacenamiento disponibles.

Valores:

• STANDARD - Bucket estándar para archivos generales (imágenes de perfil, documentos, etc.)
• ANALYTICS - Bucket para datos de analytics y métricas

Uso: Este enum probablemente se utiliza en el backend para categorizar y gestionar diferentes tipos de buckets de almacenamiento con políticas y configuraciones específicas.

---

🔗 Integración

Storage compatible

El schema storage está diseñado para integrarse con un sistema de almacenamiento S3-compatible, que proporciona:

• Almacenamiento de archivos con CDN global
• Transformaciones de imágenes automáticas
• Políticas de acceso (RLS)
• Gestión de cuotas y límites

Buckets Esperados

Basado en el enum, se esperan al menos 2 buckets:

1. Bucket STANDARD

   • Propósito: Archivos generales de usuarios
   • Contenido típico:
     • Imágenes de perfil
     • Avatares
     • Documentos subidos
     • Recursos educativos multimedia

2. Bucket ANALYTICS

   • Propósito: Datos de analytics y reportes
   • Contenido típico:
     • Reportes exportados (PDF, CSV)
     • Gráficos y visualizaciones
     • Logs de sistema

---

📊 Relaciones con Otros Schemas

Tablas que Referencian Storage

Es probable que las siguientes tablas hagan referencia a archivos en storage:

• auth_management.profiles - Avatar de usuario
• educational_content.media_resources - Recursos multimedia educativos
• content_management.media_files - Archivos de contenido
• gamification_system.achievements - Imágenes de logros/insignias

Nota: Las referencias no están en la BD directamente, sino que se manejan como URLs o paths desde el backend.

---

🔧 Uso en Backend

Servicio de Storage

El backend debería tener un servicio de storage que:

1. Crea y gestiona buckets según el tipo
2. Sube archivos al bucket apropiado
3. Genera URLs firmadas para acceso controlado
4. Aplica transformaciones de imagen
5. Gestiona políticas de acceso

Ejemplo conceptual:

// apps/backend/src/modules/storage/storage.service.ts

enum BucketType {
  STANDARD = 'STANDARD',
  ANALYTICS = 'ANALYTICS'
}

class StorageService {
  async uploadFile(file: File, bucketType: BucketType) {
    const bucket = this.getBucketName(bucketType);
    // Upload to Storage compatible
  }
}

---

📝 Configuraciones Recomendadas

Bucket STANDARD

{
  "name": "gamilit-standard",
  "public": false,
  "file_size_limit": 52428800,  // 50MB
  "allowed_mime_types": [
    "image/jpeg",
    "image/png",
    "image/gif",
    "image/webp",
    "application/pdf"
  ]
}

Bucket ANALYTICS

{
  "name": "gamilit-analytics",
  "public": false,
  "file_size_limit": 104857600,  // 100MB
  "allowed_mime_types": [
    "application/pdf",
    "text/csv",
    "application/json"
  ]
}

---

🛡️ Seguridad

Políticas RLS Recomendadas

Para el bucket STANDARD:

• Usuarios autenticados pueden subir a su carpeta personal
• Administradores pueden acceder a todos los archivos
• Archivos públicos (avatares) accesibles sin auth

Para el bucket ANALYTICS:

• Solo administradores y teachers pueden acceder
• Exportaciones personales solo por el usuario creador

---

📈 Métricas y Monitoring

Métricas Importantes

1. Uso de almacenamiento por bucket
2. Número de archivos por tipo
3. Ancho de banda consumido
4. Errores de upload/download
5. Transformaciones de imagen ejecutadas

---

🔗 Referencias

• Schema: apps/database/ddl/schemas/storage/
• Enum: apps/database/ddl/schemas/storage/enums/buckettype.sql
• Storage compatible Docs: S3/Storage compatible
• Backend (estimado): apps/backend/src/modules/storage/

---

⚠️ Notas

• ✅ Enum definido y listo para uso
• ⚠️ No hay tablas en este schema (integración externa)
• ⚠️ Backend y políticas de storage requieren implementación/documentación
• 📋 Considerar agregar más tipos de buckets si es necesario:
  • BACKUPS - Para respaldos de sistema
  • TEMP - Para archivos temporales con auto-delete
  • ARCHIVE - Para archivos archivados (cold storage)

---

🎯 Próximos Pasos

1. Documentar servicio de storage en backend
2. Crear políticas RLS para buckets
3. Implementar gestión de cuotas por tenant
4. Configurar CDN y transformaciones de imagen
5. Crear sistema de limpieza de archivos huérfanos

---

Creado: 2025-11-08 Tipo: Documentación retroactiva Estado: ✅ Documentación básica completa