gkachele-saas/memoria/DOCUMENTACION_PROYECTO.md

📖 Documentación del Proyecto - GKACHELE™

© 2025 GKACHELE™. Todos los derechos reservados.

🎯 ¿Qué Estamos Construyendo?

Un SaaS (Software as a Servicio) para que clientes creen y gestionen sus propios sitios web, similar a sistemas populares pero mejorado y personalizado.

Funcionalidad Principal:

• Clientes se registran → Crean su sitio → Lo personalizan → Lo publican
• Todo desde una interfaz web simple
• Sistema multi-tenant (todos los clientes en una sola base de datos)

---

🏗️ Arquitectura Técnica

¿Por qué Python/Flask y NO Docker?

Sí, es por la Raspberry Pi:

• Raspberry Pi tiene recursos limitados
• Docker consume más memoria y CPU
• Python directo es más ligero y eficiente
• Más fácil de depurar y mantener
• En VPS podrías usar Docker si quieres, pero Python directo también funciona perfecto

Stack Tecnológico:

• Backend: Flask (Python 3)
• Base de Datos: SQLite (main.db - multi-tenant)
• Frontend: HTML, CSS, JavaScript
• Servidor Web: Nginx (reverse proxy)
• Hosting: Raspberry Pi 3 (actual) / VPS (recomendado para producción)

---

🗄️ Base de Datos

Estructura Multi-tenant:

TODO en una sola base de datos (main.db):

• users - Todos los usuarios/clientes
• sites - Todos los sitios (filtrados por user_id)
• menus - Menús dinámicos
• widgets - Widgets dinámicos
• content - Contenido
• settings - Configuraciones
• requests - Solicitudes de publicación
• media - Archivos subidos

Acceso a Base de Datos:

• Tu acceso: Panel /admin (solo rol administrator)
• Acceso clientes: Solo ven SUS datos (filtrado por user_id)
• Herramientas: DB Browser for SQLite, scripts Python (ver_usuarios.py, limpiar_db.py)

---

👥 Sistema de Usuarios y Roles

Roles (desde Base de Datos):

• administrator - Acceso total (tú)
• editor - Puede editar contenido
• author - Puede crear contenido
• subscriber - Solo lectura

Admin para Clientes:

• Panel /dashboard - Cliente ve SUS sitios
• Panel /customizer/{site_id} - Personalizar sitio
• Panel /dashboard/admin - Admin del cliente (media, config)

---

🔒 Limitaciones por Plan

Sistema Actual:

• Planes: base, premium, etc. (campo en tabla users)
• Limitaciones posibles:
  • Número de sitios
  • Subida de fotos (tamaño, cantidad)
  • Modificaciones (frecuencia, tipo)
  • Funcionalidades avanzadas

Implementación:

• Verificar plan antes de acciones
• Contar recursos usados vs. límites del plan
• Bloquear acciones si excede límite

---

📊 Detección de Movimientos

Sistema Actual:

• No hay detección automática de movimientos aún
• Registros disponibles:
  • created_at - Fecha de creación
  • updated_at - Fecha de actualización
  • Logs del servidor (journalctl)

Posibles Mejoras:

• Tabla activity_log para registrar acciones
• Notificaciones de cambios
• Historial de modificaciones
• Auditoría de cambios

---

🚀 VPS vs Raspberry Pi

Raspberry Pi (Actual):

• ✅ Bajo costo
• ✅ Suficiente para desarrollo/pruebas
• ❌ Recursos limitados
• ❌ Puede ser lento con muchos clientes

VPS (Recomendado para Producción):

• ✅ Más recursos (CPU, RAM, disco)
• ✅ Mejor rendimiento
• ✅ Más confiable
• ✅ Mejor para escalar
• ✅ Puedes usar Docker si quieres
• ✅ Mismo código funciona (solo cambiar configuración)

Migración a VPS:

1. Copiar código completo
2. Instalar Python3, Nginx
3. Copiar configuración
4. Cambiar dominio
5. Configurar SSL (Let's Encrypt)
6. Mismo código, más potencia

---

🔄 Flujo Completo del Sistema

1. Cliente → Landing Page
2. Cliente → Registro (/register)
   ├── Crea usuario en `users`
   ├── Crea sitio automático en `sites`
   └── Crea menús por defecto en `menus`
3. Cliente → Login (/login)
   └── Redirige a `/customizer/{site_id}` (directo)
4. Cliente → Customizer
   ├── Personaliza contenido
   ├── Cambia colores, tipografía
   └── Gestiona menús y widgets
5. Cliente → Envía para aprobación
   └── Crea solicitud en `requests`
6. Admin → Aprueba desde `/admin`
   └── Cambia status a `published`
7. Sitio → Público en `/site/{slug}`

---

📁 Estructura del Proyecto

c:\word\
├── demo/                    # Código principal
│   ├── app.py              # Flask backend (TODO aquí)
│   ├── database/
│   │   └── main.db         # Base de datos multi-tenant
│   ├── themes/             # Templates
│   │   ├── _gkachele/      # Sistema modular (header.php, footer.php, sidebar.php)
│   │   └── {tema}/         # Temas específicos
│   ├── templates/          # HTML templates
│   └── static/             # CSS, JS
├── memoria/                 # 📚 TODA LA DOCUMENTACIÓN
└── backups/                 # Backups automáticos

---

🎯 Estado Actual

✅ Funcionando:

• Registro de clientes
• Login (redirige a customizer)
• Dashboard del cliente
• Customizer (personalización)
• Sistema de menús y widgets
• Panel admin (ver/eliminar usuarios)
• Sistema de roles basado en DB

⚠️ Pendiente:

• Limitaciones por plan
• Detección de movimientos/actividad
• Mejorar landing page
• Integración Gitea
• UI completa para gestionar menús

---

🔐 Seguridad

• Passwords hasheados (Werkzeug)
• Sesiones Flask
• Filtrado por user_id (cada cliente solo ve sus datos)
• Roles desde base de datos (no hardcodeados)
• Verificación de permisos en cada ruta

---

📝 Próximos Pasos

1. Implementar limitaciones por plan
2. Sistema de actividad/logs
3. Mejorar UI del customizer
4. Optimizar para VPS
5. Añadir más funcionalidades

---

Última actualización: 14 Enero 2025
Hash: gkachele-documentacion-completa-20250114

---

© 2025 GKACHELE™. Todos los derechos reservados.