Ir al contenido

Desarrolladores

Artist Alley es de código abierto y está escrito principalmente en Go (el backend se compila en un único binario) y Svelte 5 (SPA de frontend, incrustada mediante go:embed al publicar una versión). Se distribuye como una imagen de Docker; los artefactos de cada versión se describen en la referencia para desarrolladores. El código fuente está en github.com/Artist-Alley-Org/artist-alley.

El binario de Go es el runtime. Se encarga de:

  • El servidor HTTP en /api/v1/... (OpenAPI primero; la especificación está en app/api/openapi.yaml). Los endpoints IIIF también se sirven en /iiif/... para visores externos.
  • El estado persistente en Postgres mediante sqlc (consultas en app/internal/<domain>/queries.sql, Go generado en queries.sql.go).
  • Una cola de trabajos para previsualizaciones, ingesta, búsqueda y trabajo de IA, además de las acciones programadas. La entrega de la federación se ejecuta en su propia cola de salida (outbox).
  • Una abstracción de almacenamiento con backends intercambiables: el sistema de archivos por defecto, o cualquier bucket compatible con S3 con AA_STORAGE_BACKEND=s3. El perfil de Compose storage-s3 solo arranca MinIO para pruebas locales.
  • El frontend incrustado: las compilaciones de versión (la build tag embed_web) empaquetan la salida de la compilación de SvelteKit con go:embed y la sirven desde el mismo binario. En desarrollo, el binario solo sirve la API, IIIF y las comprobaciones de estado; Vite sirve el frontend en localhost:5173 y reenvía las peticiones /api e /iiif al backend, por defecto a través del nginx de la pila de Compose.

Hoy no se distribuye ningún add-on. Las integraciones de IA opcionales (embeddings de texto, transcripción y edición de imágenes mediante un puente con ComfyUI) forman parte del binario, están desactivadas por defecto y se conectan a servidores de modelos que ejecuta el operador o a APIs de proveedores alojadas externamente que el operador configura; son experimentales. La búsqueda por imagen está construida solo en parte, pero el sidecar de CLIP del que depende aún no tiene una configuración compatible; hay una versión empaquetada prevista junto con los add-ons instalables. Las miniaturas 3D se renderizan dentro del contenedor de la aplicación, con el Node y el Chromium headless que incluye la imagen, así que no hace falta ningún contenedor adicional. El registro de add-ons de capacidades está previsto para la v0.17.0. Consulta el ADR 0034.

El backend sigue una organización por dominio bajo app/internal/<domain>/. Cada dominio suele tener:

  • handler.go: los handlers HTTP y los adaptadores entre los tipos generados a partir de OpenAPI y el modelo del dominio.
  • queries.sql: las consultas SQL gestionadas por sqlc.
  • queries.sql.go: el Go generado (no lo edites a mano; regénéralo con ./scripts/generate.sh).
  • handler_test.go: pruebas de integración contra un Postgres real (sin mocks de la base de datos; consulta los estándares de código).

El frontend sigue una organización por ruta bajo web/src/routes/, con componentes compartidos en web/src/lib/components/. Las runas ($state, $derived, $effect) de Svelte 5 son la primitiva de gestión de estado. Funcionan en componentes .svelte y en módulos .svelte.js o .svelte.ts, pero no en archivos .ts normales; este proyecto coloca el estado compartido con runas en módulos .svelte.ts.

La versión corta:

  1. Crea tu rama a partir de dev (la rama de integración; main es solo para código estable). Los nombres de rama usan el prefijo feat/..., fix/... o chore/....
  2. Ejecuta ./scripts/test.sh hasta que pase antes de abrir una PR. Lanza las pruebas de integración de Go contra un Postgres real en la pila de desarrollo en ejecución; la comprobación de tipos del frontend es un paso aparte (consulta los estándares de código).
  3. Las PR apuntan a dev. Al publicar una versión, dev llega a main mediante un merge commit, y main es el origen de las versiones.
  4. Mensajes de commit: <area>: <imperative summary> (p. ej., assets: handle 0-byte uploads). Sin coautoría de Claude/IA.

La versión completa está en los estándares de código.

Cuando una decisión es lo bastante importante como para tener que explicarla meses después (topología del backend, modelo de licencia, postura de seguridad, forma de la monetización), se recoge en un Architecture Decision Record. El catálogo de ADR es la respuesta de referencia a «¿por qué el proyecto tiene esta forma?»; la propia convención es el ADR 0035.