Ir al contenido

Arquitectura

Artist Alley es pequeño a propósito. Un único programa Go sirve tanto la API como la aplicación web, Postgres guarda los registros y un backend de almacenamiento guarda los archivos. Puedes poner tu propio proxy inverso delante para el TLS. Las integraciones opcionales se conectan a servicios externos a la aplicación, como un servidor de modelos de IA. Esta página explica cómo se relacionan esas piezas y por qué se eligieron. La guía de instalación explica cómo ejecutarlo.

flowchart LR
  user["Artista / Revisor / Operador"]
  proxy["Reverse proxy<br/>nginx o el suyo, TLS"]
  subgraph host["Host de la aplicación"]
    app["Contenedor de Artist Alley<br/>Binario de Go: API + aplicación web integrada<br/>más herramientas multimedia"]
    fs[("Sistema de archivos local<br/>backend de almacenamiento fs")]
  end
  pg[("Postgres<br/>mismo host o servicio aparte")]
  s3[("Almacenamiento de objetos compatible con S3<br/>backend de almacenamiento s3, puede ser remoto")]
  ext["Servicios opcionales<br/>proveedores de IA, servidores de modelos"]
  user -->|"HTTPS, despliegues públicos"| proxy
  proxy -->|"reenvía a"| app
  user -.->|"HTTP, redes locales o de confianza"| app
  app --> pg
  app -->|"backend fs"| fs
  app -.->|"o backend s3"| s3
  app -.->|"solo si está configurado"| ext

Dicho con palabras: un despliegue público llega a la aplicación por HTTPS a través de un proxy inverso, mientras que el HTTP directo a la aplicación es para redes locales o de confianza. La aplicación lee y escribe en Postgres, que puede ejecutarse en el mismo host o como un servicio aparte. Guarda los archivos en un único backend configurado: o bien un directorio en el host de la aplicación, o bien un bucket compatible con S3, que puede estar en cualquier parte. Las integraciones de IA opcionales llaman a los servicios que un administrador ha configurado.

  • El binario de Go sirve la API JSON y la aplicación web SvelteKit, que está compilada dentro de él con go:embed, de modo que un solo programa sirve ambas. Las compilaciones de producción usan la etiqueta de compilación embed_web. Sin ella, en desarrollo, el binario sirve solo la API, y el servidor de desarrollo de Vite sirve el frontend y redirige las solicitudes /api e /iiif al backend.
  • La imagen del contenedor empaqueta ese binario con las herramientas de línea de comandos que ejecuta para generar vistas previas y miniaturas: ffmpeg, ImageMagick, Ghostscript, Poppler, librsvg y unar, además de Node y un Chromium headless para renderizar las vistas previas 3D. Vienen dentro de la imagen; no las ejecutas como servicios aparte.
  • Postgres guarda todos los registros que gestiona Artist Alley: assets, campos de metadatos y sus valores, posts, miembros, colecciones, comentarios, «me gusta», sesiones, auditoría y ajustes de la instalación. Necesita la extensión pgvector (Postgres). Las migraciones están en app/internal/db/migrations/, se compilan dentro del binario y se ejecutan cuando este arranca.
  • El almacenamiento de archivos guarda los bytes y está direccionado por contenido: cada archivo almacenado tiene como clave su SHA-256, de modo que los mismos bytes solo se almacenan una vez, y los archivos se organizan por hash en lugar de en carpetas de proyecto. Configuras uno de los dos backends:
    • fs: un directorio en el host de la aplicación (montado en el contenedor)
    • s3: cualquier servicio de almacenamiento con una API compatible con S3, local o remoto
  • Un proxy inverso como nginx es opcional en una red local o de confianza. El binario sirve HTTP simple y no termina el TLS por sí mismo, así que un despliegue público debería ir detrás de un proxy que ofrezca HTTPS, como el que ya ejecutas.

Postgres y el almacenamiento de archivos son ambos estado duradero, y ninguno sirve sin el otro: la base de datos sabe qué hash pertenece a qué asset, y el almacenamiento guarda los bytes. Una copia de seguridad que puedas restaurar tiene tres partes: la base de datos, los archivos almacenados y las dos claves de la instancia (Copia de seguridad).

La API JSON se define en app/api/openapi.yaml. Ese archivo es el contrato: los tipos del servidor y las interfaces de los handlers se generan a partir de él con oapi-codegen, y el frontend genera sus tipos de TypeScript a partir del mismo archivo con openapi-typescript.

Cambiar la API pública significa cambiar primero la especificación. Un handler cuya firma en Go se desvíe de la interfaz generada no compilará. En CI, el job del frontend regenera los tipos de TypeScript y comprueba los tipos de la aplicación contra ellos, y otro job aparte de detección de desvíos en el código generado vuelve a ejecutar los generadores y falla si el código generado que está en el repositorio está desactualizado. Eso detecta los desvíos de tipos entre la especificación, el servidor y el frontend. No demuestra cómo se comporta la API en tiempo de ejecución; para eso están las suites de pruebas.

La referencia generada está en la referencia de la API y se reconstruye a partir de la misma especificación en cada compilación del sitio.

El esquema de Postgres se declara en app/internal/db/migrations/*.sql y se documenta tabla por tabla en el esquema de la base de datos. Las migraciones son la fuente de verdad: la base de referencia de la v0.1.0 (00001_baseline_v0_1.sql) más las migraciones añadidas después. Según el ADR 0046, las migraciones se añaden libremente durante la beta, y el plan es fusionarlas en una nueva base de referencia en la v1.0.0.

app/schema.sql se produce a partir de las migraciones: se ejecutan sobre una base de datos vacía y se vuelca el esquema resultante. sqlc lee ese archivo versionado para comprobar los tipos de las consultas de Go cuando se genera el código, de modo que una consulta que ya no coincida con sus tablas hace fallar la generación. El job de detección de desvíos de CI regenera el código a partir del schema.sql versionado y falla si el código generado que está en el repositorio está desactualizado. No reconstruye schema.sql a partir de las migraciones, así que no puede decirte si ambos discrepan; regenerar el archivo forma parte de añadir una migración, y su cabecera indica los pasos.

Hay dos capas:

  • La configuración del proceso (conexión a la base de datos, claves, backend de almacenamiento, dirección de escucha, registros) procede de variables de entorno; consulta la referencia de configuración de la guía de instalación.
  • Los ajustes de toda la instalación (nombre del sitio, SMTP, proveedores de autenticación, proveedores de IA, fuentes de marca, temas) se almacenan como filas de tipo JSON en la tabla system_config. Se cambian desde la interfaz de administración y se exponen a través de la API /admin/system/*. La clave appearance, por ejemplo, controla el selector de ranuras de fuentes de cada instalación.

Los ajustes de la instalación nunca se federan: se quedan en la instancia a la que pertenecen. Los perfiles de usuario registran de qué servidor procede cada usuario.

  • Go para el servidor: el servidor de la API, las migraciones de la base de datos y la aplicación web integrada se compilan en un solo binario, que es el punto de entrada del contenedor (/app/aa). El transporte en tiempo real de las sesiones de revisión en directo previstas aún no está decidido.
  • SvelteKit para la aplicación web: con adapter-static, el resultado de la compilación son archivos simples, así que no hay un servidor de interfaz aparte que desplegar ni mantener en marcha. Sus tipos proceden de la misma especificación que los del servidor, como se describe en API guiada por contrato.
  • Solo Postgres: los registros relacionales, la búsqueda de texto completo y los vectores comparten una sola base de datos, de modo que los únicos servicios obligatorios son la aplicación y Postgres, y no hay un servicio de búsqueda, un almacén vectorial ni un servidor de caché aparte que ejecutar y respaldar. La búsqueda de texto completo es una columna tsvector que los triggers reconstruyen en cada escritura, y pgvector, en la misma base de datos, almacena los embeddings que producen las integraciones de IA opcionales. Esas integraciones son experimentales, se conectan a servidores de modelos o API de proveedores que configura un administrador y no incluyen ningún modelo. La búsqueda por imagen está construida en parte en la misma base de datos, pero el sidecar de CLIP del que depende todavía no tiene una configuración admitida; está prevista una versión empaquetada con los complementos instalables.
  • go:embed para la aplicación web: los recursos web se incorporan al mismo binario que la API, de modo que la interfaz y el servidor siempre se despliegan juntos y en la misma versión, y no hay un despliegue de recursos estáticos que mantener sincronizado.
  • Almacenamiento direccionado por contenido: subir dos veces los mismos bytes los almacena una sola vez, y puedes verificar cualquier archivo volviendo a calcular su hash y comparándolo con su clave. La contrapartida es la que se describe más arriba: el almacenamiento solo tiene sentido junto con la base de datos, así que un traslado o una restauración requiere las tres partes de una copia de seguridad, como explica la guía de copias de seguridad.

Para el razonamiento detrás de cada gran decisión, consulta las decisiones de arquitectura.