Ir al contenido

Referencia para desarrolladores

El código fuente de Artist Alley está en github.com/Artist-Alley-Org/artist-alley. Esta página es el mapa: la estructura de primer nivel, el patrón por dominio del backend, la estructura del frontend, las piezas de infraestructura y el recorrido de un cambio desde una edición local hasta una publicación.

artist-alley/
├── app/ The Go backend + the OpenAPI spec
│ ├── api/openapi.yaml HTTP contract: generates the Go strict server + TS types
│ ├── cmd/ Binary entry points (server, CLI tools)
│ ├── internal/ Per-domain Go packages (see below)
│ ├── schema.sql Postgres schema the Go side sees
│ ├── sqlc.yaml sqlc configuration
│ └── web/ Standalone login, logout and setup HTML pages
├── web/ The Svelte 5 frontend source
│ ├── src/
│ │ ├── routes/ SvelteKit page routes
│ │ └── lib/
│ │ ├── api/ Generated API types + the typed fetch client
│ │ ├── components/ Shared components
│ │ ├── stores/ Svelte runes / stores
│ │ ├── i18n/ Per-locale catalogues
│ │ └── playlist/, whiteboard/, sprite/ Feature modules
│ └── package.json
├── docs/ Long-form docs (markdown): the site pulls these
│ └── adr/ Architecture Decision Records (canonical source)
├── infra/
│ ├── docker/ Dockerfiles + compose stacks
│ ├── nginx/ Reverse-proxy config
│ └── postgres/ DB init + extension setup
├── scripts/ Dev, CI and seed scripts (bootstrap.sh, test.sh, generate.sh, etc.)
├── Dockerfile The release image: Go binary with the web app embedded
├── docker-compose.yml The dev stack: nginx, app, web, postgres; minio and a second dogfood instance behind profiles
├── CONTRIBUTING.md High-level contribution flow
└── RELEASING.md Release cut procedure

El frontend incrustado no se guarda en el repositorio: la compilación de la imagen copia la salida de SvelteKit en app/internal/http/static_assets/ antes de compilar el binario.

El backend de Go sigue una organización por dominio bajo app/internal/<domain>/. Cada dominio es dueño de un área de capacidad y es autocontenido.

app/internal/<domain>/
├── handler.go HTTP handlers + adapters between OpenAPI types and the domain model
├── handler_test.go Integration tests against a real Postgres
├── queries.sql sqlc-managed queries
├── queries.sql.go Generated; do not edit
└── service.go (optional) Cross-handler business logic that doesn't belong in a handler

Algunos de los dominios principales (app/internal/ contiene muchos más, entre ellos federation, search, visibility, notifications, email, licensing e iiif):

DominioQué posee
assetsLa entidad central de asset, su ciclo de vida y los metadatos de archivo
assettypeLa tabla de consulta de tipos de asset
metadataDefiniciones de campos, valores de campos de los assets e historial
collectionsColecciones de posts, con ACL
postsPosts que envuelven uno o varios assets
socialComentarios y «me gusta»
authSesiones, inicio de sesión y gestión de contraseñas
aclsComprobaciones de listas de control de acceso por fila
users, teamsSuperficies de identidad
auditRegistro de eventos de auditoría
cacheRegistro de caché en memoria con invalidación entre dominios
config, sysconfigSuperficies de configuración del sistema
dbMigraciones y utilidades de base de datos de bajo nivel
httpArranque del servidor HTTP y middleware
sitetextSobrescrituras del operador de las cadenas de la interfaz, aplicadas sobre el catálogo en.json incluido
jobsCola de trabajos asíncronos
openapiTipos generados del servidor estricto
previewPipeline de generación de miniaturas y previsualizaciones
setupEndpoints del instalador de primer arranque, inactivos en cuanto existe un admin (una instalación normal crea uno al arrancar)
storageBackend de almacenamiento intercambiable (fs / S3)
workflowMáquina de estados de assets y posts
abr, brushpacksImportación de pinceles .abr de Photoshop y paquetes de pinceles para la herramienta de bocetos
loggingConfiguración del registro estructurado (slog) de todo el proceso; el envío de registros está previsto

Todo se ejecuta en un único proceso: ningún dominio llama a otro por HTTP. Las llamadas entre dominios pasan por:

  • Dependencias pequeñas y concretas cuando un dominio necesita una capacidad de otro (p. ej., los handlers que emiten eventos reciben un *audit.Recorder, y algunos declaran una interfaz más estrecha sobre él).
  • El registro de caché (cache.Registry) para la invalidación entre paquetes. Usa LISTEN/NOTIFY de Postgres, de modo que varios procesos de la aplicación que comparten una base de datos descartan juntos las entradas obsoletas; no sincroniza instancias federadas.

Lo que esta organización pretende evitar: que un dominio importe directamente el repositorio o los tipos de consulta de otro dominio. Ese acoplamiento es precisamente lo que la organización por dominio existe para impedir; los pocos lugares que todavía leen las consultas de otro dominio (parte del código de previsualización y de entrega de archivos lee las consultas de assets) son excepciones, no el patrón.

web/src/
├── routes/ SvelteKit page routes: file-system-mapped URLs
│ ├── +layout.svelte Root layout
│ ├── +page.svelte Browse feed (the home page)
│ ├── admin/ Admin shell (capability-gated)
│ ├── account/ Account preferences
│ └── ...
└── lib/
├── api/ schema.d.ts is generated from openapi.yaml (don't edit it); client.ts is hand-written
├── components/ Shared components consumed across routes
│ ├── viewers/ Universal asset viewer + per-kind view bodies
│ ├── whiteboard/ Sketch annotation tool and brush packs
│ └── ...
├── stores/ Cross-route runes + Svelte stores
├── i18n/ en.json + locale catalogues
└── util/ Pure functions and browser/Svelte helpers

Las runas ($state, $derived, $effect) funcionan en componentes .svelte y en módulos .svelte.js o .svelte.ts; en un archivo .ts normal no se compilan. El estado compartido con runas va en módulos .svelte.ts; consulta los estándares de código.

Los tipos generados se actualizan con npm run generate:api tras cada cambio en openapi.yaml. El archivo de esquema está en gitignore, así que una copia desactualizada solo afecta a tus comprobaciones locales: la CI lo genera de nuevo a partir de openapi.yaml antes de comprobar los tipos del frontend con svelte-check.

infra/
├── docker/ Dev Dockerfiles for app and web, plus CI + dogfood compose files
├── nginx/ Reverse-proxy config for the Compose stack
└── postgres/ Init scripts + extensions (vector, pg_trgm, uuid-ossp, pgcrypto)

La pila de desarrollo se levanta con docker compose up. Perfiles opcionales:

  • --profile storage-s3: ejecuta MinIO para probar el backend S3. El desarrollo diario usa el backend de sistema de archivos; MinIO es solo para verificación.
  • --profile dogfood: levanta una segunda instancia (estudio B) con su propio Postgres y su propio proxy inverso, para probar la federación entre dos pares en local.

La generación de miniaturas 3D no necesita ningún perfil. Un worker de three.js headless (Node y Chromium, incluidos en la imagen de la aplicación) las renderiza dentro del contenedor de la aplicación, y lo hace desde la v0.6.0.

El binario de Go es el runtime. Cada versión publica un único artefacto:

  • Una imagen de Docker multiarquitectura (amd64 + arm64) (ghcr.io/artist-alley-org/artist-alley, replicada en Docker Hub), firmada sin clave (keyless) con Sigstore.

Los binarios nativos, los paquetes .deb / .rpm con una unidad de systemd y una fórmula de Homebrew están previstos para la v0.22.0 y son un requisito previo a la v1.0.0, con seguimiento en #242.

Ventana de terminal
# Bring up the stack
docker compose up -d
# Tail logs
docker compose logs -f app web
# Run the Go tests (against a separate test database, reset each run)
./scripts/test.sh
# Run the frontend type-check
docker compose exec -T web sh -c 'cd /app && npm run check'

Tras un cambio en el binario de Go que no se recoge: docker compose up -d --build --force-recreate app. Sin --force-recreate, compose puede seguir ejecutando el binario antiguo.

Las ediciones del frontend se recargan en caliente mediante Vite, que en esta configuración consulta periódicamente (polling) los cambios en los archivos. Tras cambiar vite.config.ts o las dependencias, recrea el contenedor web: docker compose up -d --force-recreate web.

Cuando Postgres se comporta mal: primero docker compose logs postgres. Fallos de migración, problemas de bloqueos, roles borrados: el diagnóstico está en el registro de Postgres, no en el de la aplicación.

feat/* → dev → main → tag → publicación.

  • Las ramas de trabajo se fusionan en dev mediante PR (./scripts/test.sh debe pasar).
  • dev → main ocurre en los hitos de publicación mediante una PR fusionada con un merge commit.
  • El tag de versión (v0.X.Y) en main dispara el pipeline de GitHub Actions que compila la imagen de Docker multiarquitectura, la firma con Sigstore, la publica en GHCR y Docker Hub y publica las notas de la versión. (Los binarios y paquetes nativos están previstos para la v0.22.0 con #242, como requisito previo de la v1.0.0.)
  • Los jobs de CI y de publicación se ejecutan en el runner autoalojado con la etiqueta [artist-alley].
  • Procedimiento completo en RELEASING.md.

Dónde está lo que buscas con más frecuencia

Sección titulada «Dónde está lo que buscas con más frecuencia»
Qué buscasRuta
Rutas HTTP y formas de petición/respuestaapp/api/openapi.yaml
El SQL que se ejecuta en Postgresapp/internal/<domain>/queries.sql
El esquema sobre el que puedes hacer consultasapp/schema.sql
La documentación de una tabla concreta/developers/database/<table>/
Historial de migracionesapp/internal/db/migrations/NNNNN_*.sql
Por qué elegimos X en lugar de Y/adr/: el catálogo de ADR
En qué punto de la hoja de ruta está una función/roadmap/ (en inglés)
Cómo se ve un componente del frontendweb/src/lib/components/<area>/
Una cadena de idiomaweb/src/lib/i18n/<locale>.json
Contenedores de la pila de desarrollodocker-compose.yml
Procedimiento de publicaciónRELEASING.md
Flujo de contribuciónCONTRIBUTING.md + estándares de código