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.
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».
| 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 |
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.
-
01
Entra por el servidor web
Nginx delante, Gunicorn detrás y un único punto de entrada.
wsgi.pyresuelveQUARUM_ROOT, lee el.envy llama acreate_app(). Es el único código de la instancia.
-
02
Sesión y permisos
Flask-Login comprueba la sesión; el decorador, el permiso.
@verify_permission('read')consulta_qcore_permissionpor clase y grupo antes de ejecutar la vista.
-
03
La vista del payload
La ruta que escribe el proyecto, o la que sirve el panel.
- Consulta con
newQuery(), guarda consaveForm()y, tras el commit, dispara los cálculos deevents.py.
- Consulta con
-
04
Persistencia y salida
MySQL o MariaDB con InnoDB; la plantilla o el exportador.
- El borrado es lógico (
deletedAt), el original vive enuploads/o en el bucket, y la salida es HTML, CSV o PDF.
- El borrado es lógico (
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.
-
quarumes la rama del framework: sus tablas_qcore_*y su cabeza viven en el paquete. -
appes la rama del proyecto: sus tablas de contenido y su propia cabeza, enmigrations/versions/. -
La primera revisión de
appdepende dequarum, así que el orden no se decide a mano. -
Se migra con
quarum upgrade(las dos ramas) o conflask db migrate --head app@headcuando el cambio es del proyecto. -
En una instalación nueva,
quarum upgradesiembra la revisión de arranque de la ramaapp: 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.
3.5.12