Saltar al contenido
3.5.12
Arquitectura

Tres capas y una frontera que se puede señalar

La pregunta que resuelve esta arquitectura no es «cómo organizo el código», sino otra: qué pasa cuando hay que actualizar el framework sin reescribir la aplicación. La respuesta es que el framework no vive dentro del proyecto.

Reparto

Qué es de quién

Cada fichero tiene una capa y una sola. Cuando algo no encaja, la respuesta suele ser «decláralo en el payload», no «cópialo dentro del framework».

El mapa, tal como lo reparte quarum maintenance layers
Fichero o carpeta Capa Quién lo cambia
quarum/ (el paquete instalado) Framework El equipo del framework, con una versión nueva
project/develop.py Payload El proyecto
classes/*.json Payload El proyecto, exportando desde el panel o desde la base
project/models/production/ Payload Nadie a mano: es salida del generador
plugins/<nombre>/ Payload El proyecto
migrations/versions/ Payload El proyecto, con una revisión por cambio
.env, wsgi.py, uploads/ Instancia Cada despliegue
En marcha

El recorrido de una petición

Sin pasos ocultos: lo que sigue es el camino real de una petición al panel, con el sitio donde ocurre cada cosa.

  1. 01

    Entra por el servidor web

    Nginx delante, Gunicorn detrás y un único punto de entrada.

    • wsgi.py resuelve QUARUM_ROOT, lee el .env y llama a create_app(). Es el único código de la instancia.
  2. 02

    Sesión y permisos

    Flask-Login comprueba la sesión; el decorador, el permiso.

    • @verify_permission('read') consulta _qcore_permission por clase y grupo antes de ejecutar la vista.
  3. 03

    La vista del payload

    La ruta que escribe el proyecto, o la que sirve el panel.

    • Consulta con newQuery(), guarda con saveForm() y, tras el commit, dispara los cálculos de events.py.
  4. 04

    Persistencia y salida

    MySQL o MariaDB con InnoDB; la plantilla o el exportador.

    • El borrado es lógico (deletedAt), el original vive en uploads/ o en el bucket, y la salida es HTML, CSV o PDF.
Esquema

Dos ramas de migraciones, no una

Si el framework y la aplicación comparten una sola historia de Alembic, cada actualización del framework te obliga a resolver un conflicto en el historial del proyecto. Aquí cada capa tiene su cabeza y la aplicación cuelga de la del framework con una dependencia explícita: actualizar Quarum es una línea en el despliegue, no un fin de semana de merges.

  • quarum es la rama del framework: sus tablas _qcore_* y su cabeza viven en el paquete.
  • app es la rama del proyecto: sus tablas de contenido y su propia cabeza, en migrations/versions/.
  • La primera revisión de app depende de quarum, así que el orden no se decide a mano.
  • Se migra con quarum upgrade (las dos ramas) o con flask db migrate --head app@head cuando el cambio es del proyecto.
  • En una instalación nueva, quarum upgrade siembra la revisión de arranque de la rama app: sin ella, «cabeza de la aplicación» no existe y la primera migración duele.

El detalle, con los comandos y el orden correcto, en Migraciones y en El esquema.

El framework no conoce tu proyecto. Y eso es la ventaja.

El payload se declara en project/develop.py y Quarum lo lee por una única puerta. Por eso puedes actualizar el motor sin que nadie revise tu aplicación, y por eso dos clientes comparten framework sin compartir base de datos, secretos ni datos. Si algo no se puede hacer sin tocar el paquete, se declara o se escribe un plugin: nunca se copia el framework dentro del proyecto.

Leer el contrato