Skip to content

Developers

Artist Alley is open source, written primarily in Go (the backend compiles to one binary) and Svelte 5 (frontend SPA, embedded via go:embed at release time). It’s distributed as a Docker image; see the developer reference for the release artifacts. The source is at github.com/Artist-Alley-Org/artist-alley.

The Go binary is the runtime. It owns:

  • HTTP server at /api/v1/... (OpenAPI-first; spec at app/api/openapi.yaml). The IIIF endpoints are also served at /iiif/... for external viewers.
  • Postgres-backed persistent state via sqlc (queries in app/internal/<domain>/queries.sql, generated Go in queries.sql.go).
  • Job queue for previews, ingest, search and AI work, and scheduled actions. Federation delivery runs on its own outbox queue.
  • Storage abstraction with pluggable backends: the filesystem by default, or any S3-compatible bucket with AA_STORAGE_BACKEND=s3. The storage-s3 compose profile only starts MinIO for local testing.
  • The embedded frontend: release builds (the embed_web build tag) bundle the SvelteKit build output with go:embed and serve it from the same binary. In development the binary serves only the API, IIIF and the health checks; Vite serves the frontend on localhost:5173 and forwards /api and /iiif requests to the backend, through the Compose stack’s nginx by default.

No add-ons ship today. The optional AI integrations (text embeddings, transcription, and image editing through a ComfyUI bridge) are part of the binary, off by default, and connect to model servers the operator runs or to externally hosted provider APIs the operator configures; they are experimental. Search by image is partly built, but the CLIP sidecar it depends on has no supported setup yet; a packaged version is planned with installable add-ons. 3D thumbnails render inside the app’s container, using the Node and headless Chromium the image ships, so there’s no extra container. The capability add-on registry is planned for v0.17.0. See ADR 0034.

The backend follows a per-domain layout under app/internal/<domain>/. Each domain typically has:

  • handler.go: HTTP handlers + struct adapters between the OpenAPI generated types and the domain model.
  • queries.sql: sqlc-managed SQL queries.
  • queries.sql.go: generated Go (do not edit by hand; regenerate with ./scripts/generate.sh).
  • handler_test.go: integration tests against a real Postgres (no DB mocking; see coding standards).

The frontend follows a per-route layout under web/src/routes/ with shared components in web/src/lib/components/. Svelte 5 runes ($state, $derived, $effect) are the state-management primitive. They work in .svelte components and in .svelte.js or .svelte.ts modules, but not in plain .ts files; this project puts shared rune state in .svelte.ts modules.

The short version:

  1. Branch from dev (the integration branch; main is stable-only). Branch names use the feat/..., fix/..., or chore/... prefix.
  2. Run ./scripts/test.sh green before opening a PR. It runs the Go integration tests against a real Postgres in the running dev stack; the frontend type-check is a separate step (see the coding standards).
  3. PRs target dev. At release time dev reaches main through a merge commit, and main is the source of releases.
  4. Commit messages: <area>: <imperative summary> (e.g. assets: handle 0-byte uploads). No Claude/AI co-authorship.

The full version is in coding standards.

When a decision is significant enough to need explaining months later (backend topology, license model, security stance, monetization shape), it goes into an Architecture Decision Record. The ADR catalogue is the canonical answer to “why is the project shaped this way?”; the convention itself is ADR 0035.