Ir al contenido
Q
QuoteNode

Wiki

Arquitectura de QuoteNode

Resumen tecnico de la arquitectura del sistema QuoteNode: backend, frontend, base de datos y modelo de despliegue.

Arquitectura de QuoteNode

QuoteNode es una aplicacion single-tenant pensada para despliegue self-hosted. Cada instancia esta aislada y contiene su propia base de datos, almacenamiento de archivos y procesos de aplicacion.

Vision general del sistema

Navegador del cliente
     │
     ▼
Caddy (Reverse Proxy, HTTPS)
     │
     ├── /api/*    → Backend Spring Boot (Java 25)
     ├── /offer/*  → Backend Spring Boot (paginas publicas de oferta)
     └── /*        → Frontend Vue 3 (Vite, SPA)
                        │
                        ▼
                   PostgreSQL 16

Backend

El backend es una aplicacion Java 25 construida con Spring Boot 4. Se encarga de:

  • REST API - toda la logica de negocio expuesta mediante endpoints versionados
  • Authentication - sesiones con cookies cifradas y 2FA basada en TOTP
  • Authorization - control de acceso por roles con comprobaciones por endpoint
  • Database access - Spring Data JPA con migraciones Flyway
  • PDF generation - plantillas Thymeleaf renderizadas a HTML y convertidas a PDF por Gotenberg
  • Email - integracion SMTP asincrona con reintentos y logging
  • Public offer pages - HTML renderizado en servidor para enlaces publicos de oferta
  • Audit logging - trazabilidad append-only de mutaciones
  • Scheduling - jobs en segundo plano para expiracion de ofertas, anonimizado de IP y digests de notificaciones

Decisiones de diseno clave:

  • No multi-tenancy - la aplicacion sirve exactamente a una organizacion. Esto elimina complejidad de aislamiento entre tenants y simplifica el razonamiento de seguridad.
  • Flyway migrations - los cambios de esquema son solo aditivos. No se eliminan columnas; se renombran con prefijo deprecated_.
  • Immutable snapshots - los datos de la oferta se capturan como snapshot JSON en el momento del envio. Los PDF siempre se renderizan desde snapshots, nunca desde datos vivos.
  • Deterministic pricing - todos los calculos siguen un orden definido con redondeo configurable. Los resultados se almacenan para auditoria.

Frontend

El frontend es una aplicacion SPA en Vue 3 construida con Vite:

  • UI framework - biblioteca de componentes PrimeVue 4
  • Styling - Tailwind CSS 4
  • State - stores Pinia 3
  • Routing - Vue Router 5 con guards por rol
  • i18n - vue-i18n con soporte activo para ingles, polaco, aleman, frances, espanol, italiano y portugues
  • API client - cliente HTTP tipado que llama a la REST API del backend

El frontend se sirve como activos estaticos desde Caddy. Se comunica con el backend exclusivamente mediante la API REST.

Base de datos

PostgreSQL 16 es la unica base de datos soportada:

  • Schema management - migraciones Flyway que se ejecutan al arrancar el backend
  • Key entities - customers, contacts, offers, offer items, products, pricing rules, users, audit logs y notifications
  • Denormalization - los totales de oferta se guardan en una tabla dedicada para consultas rapidas
  • Views - vista de pipeline de ofertas con join lateral a los ultimos tipos FX

Generacion de PDF

La generacion de PDF usa un pipeline en dos fases:

  1. Thymeleaf renderiza el snapshot de la oferta a un documento HTML con CSS inline
  2. Gotenberg, un contenedor basado en Chromium, convierte ese HTML a un PDF listo para imprimir

Se soportan dos modos:

  • Synchronous - para ofertas con menos de 50 lineas, el PDF se genera inline en menos de tres segundos
  • Asynchronous - para ofertas grandes, un job en segundo plano procesa el PDF y notifica al usuario cuando esta listo

Despliegue

QuoteNode se despliega usando Docker Compose:

  • Backend container - Java 25 sobre Eclipse Temurin
  • Frontend container - Node 24 + Vite en desarrollo o build estatico en produccion
  • Database container - PostgreSQL 16
  • Reverse proxy - Caddy 2 con HTTPS automatico
  • PDF engine - Gotenberg
  • Mail testing - Mailpit solo en desarrollo

Toda la pila corre como un unico proyecto Docker Compose sin dependencias externas obligatorias. Puede funcionar incluso en entornos air-gapped.

Licenciamiento

Las licencias son ficheros firmados con Ed25519 y verificados offline. El sistema comprueba:

  • edicion, como Free, Pro, Business o Enterprise
  • numero maximo de usuarios
  • fecha de expiracion
  • feature flags, como white-label o plantillas avanzadas

No se consulta ningun servidor externo de licencias. Una licencia expirada no bloquea funcionalidades; el unico efecto es un badge Powered by QuoteNode en superficies orientadas al cliente y un recordatorio de renovacion en la interfaz.

Last reviewed: Recently