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.
- Para ver el desglose de carpetas del proyecto, consulta la referencia para desarrolladores.
- Para ver un resumen de las tablas de la base de datos, consulta el esquema de la base de datos.
- Todos los colaboradores deben seguir los estándares de código.
- Las superficies sensibles y el modelo de amenazas del proyecto están documentados en Seguridad en Artist Alley.
Qué hay en el binario
Sección titulada «Qué hay en el binario»El binario de Go es el runtime. Se encarga de:
- El servidor HTTP en
/api/v1/...(OpenAPI primero; la especificación está enapp/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 enqueries.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 Composestorage-s3solo 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 congo:embedy la sirven desde el mismo binario. En desarrollo, el binario solo sirve la API, IIIF y las comprobaciones de estado; Vite sirve el frontend enlocalhost:5173y reenvía las peticiones/apie/iiifal 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.
Cómo está organizado el código
Sección titulada «Cómo está organizado el código»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.
Cómo contribuir
Sección titulada «Cómo contribuir»La versión corta:
- Crea tu rama a partir de
dev(la rama de integración;maines solo para código estable). Los nombres de rama usan el prefijofeat/...,fix/...ochore/.... - Ejecuta
./scripts/test.shhasta 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). - Las PR apuntan a
dev. Al publicar una versión,devllega amainmediante un merge commit, ymaines el origen de las versiones. - 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.
Decisiones de arquitectura
Sección titulada «Decisiones de arquitectura»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.