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.
- For a breakdown of folders within the project see the developer reference.
- For an overview of the database tables see the database schema.
- All contributors must follow the coding standards.
- Security-sensitive surfaces and the project’s threat model are documented in Security in Artist Alley.
What’s in the binary
Section titled “What’s in the binary”The Go binary is the runtime. It owns:
- HTTP server at
/api/v1/...(OpenAPI-first; spec atapp/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 inqueries.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. Thestorage-s3compose profile only starts MinIO for local testing. - The embedded frontend: release builds (the
embed_webbuild tag) bundle the SvelteKit build output withgo:embedand serve it from the same binary. In development the binary serves only the API, IIIF and the health checks; Vite serves the frontend onlocalhost:5173and forwards/apiand/iiifrequests 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.
How the code is shaped
Section titled “How the code is shaped”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.
Contributing
Section titled “Contributing”The short version:
- Branch from
dev(the integration branch;mainis stable-only). Branch names use thefeat/...,fix/..., orchore/...prefix. - Run
./scripts/test.shgreen 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). - PRs target
dev. At release timedevreachesmainthrough a merge commit, andmainis the source of releases. - Commit messages:
<area>: <imperative summary>(e.g.assets: handle 0-byte uploads). No Claude/AI co-authorship.
The full version is in coding standards.
Architectural decisions
Section titled “Architectural decisions”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.