Developer reference
The Artist Alley source lives at github.com/Artist-Alley-Org/artist-alley. This page is the map: top-level layout, the per-domain backend pattern, the frontend layout, the infrastructure pieces, and how a change moves from a local edit to a release.
Top-level layout
Section titled “Top-level layout”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 procedureThe embedded frontend is not kept in the repository: the image build
copies the SvelteKit output into app/internal/http/static_assets/
before compiling the binary.
Backend per-domain layout
Section titled “Backend per-domain layout”The Go backend follows a per-domain layout under app/internal/<domain>/. Each domain owns one capability area and is self-contained.
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 handlerSome of the main domains (app/internal/ holds many more, including federation, search, visibility, notifications, email, licensing and iiif):
| Domain | What it owns |
|---|---|
assets | Core asset entity, lifecycle, file metadata |
assettype | Asset-type lookup table |
metadata | Field definitions, asset field values, history |
collections | Collections of posts, with ACLs |
posts | Posts wrapping one or many assets |
social | Comments, likes |
auth | Sessions, login, password handling |
acls | Per-row access control list checks |
users, teams | Identity surfaces |
audit | Audit-event ledger |
cache | In-memory cache registry with cross-domain invalidation |
config, sysconfig | System configuration surfaces |
db | Migrations + low-level DB helpers |
http | HTTP server bootstrap + middleware |
sitetext | Operator overrides for UI strings, layered over the shipped en.json catalogue |
jobs | Async job queue |
openapi | Generated strict-server types |
preview | Thumbnail / preview generation pipeline |
setup | First-run installer endpoints, inactive once an admin exists (a normal install creates one at boot) |
storage | Pluggable storage backend (fs / S3) |
workflow | Asset / post state machine |
abr, brushpacks | Photoshop .abr brush import + brush packs for the sketch tool |
logging | Process-wide structured logger setup (slog); log shipping is planned |
Everything runs in one process: no domain calls another over HTTP. Cross-domain calls go through:
- Small, focused dependencies when one domain needs a capability from another (e.g. handlers that emit events receive an
*audit.Recorder, and some declare a narrower interface over it). - The cache registry (
cache.Registry) for invalidation across packages. It uses Postgres LISTEN/NOTIFY, so several app processes sharing one database drop stale entries together; it doesn’t synchronize federated instances.
What the layout aims to avoid: one domain importing another domain’s repository or query types directly. That coupling is the thing the per-domain layout exists to prevent; the few places that still read another domain’s queries (some preview and file-serving code reads assets queries) are exceptions, not the pattern.
Frontend layout
Section titled “Frontend layout”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 helpersRunes ($state, $derived, $effect) work in .svelte components and in .svelte.js or .svelte.ts modules; in a plain .ts file they aren’t compiled. Shared rune state goes in .svelte.ts modules; see coding standards.
The generated types are refreshed by npm run generate:api after every openapi.yaml change. The schema file is gitignored, so a stale copy only affects your local checks: CI generates it fresh from openapi.yaml before type-checking the frontend with svelte-check.
Infrastructure
Section titled “Infrastructure”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)The dev stack is brought up with docker compose up. Optional profiles:
--profile storage-s3: runs MinIO for S3-backend testing. Daily dev uses the filesystem backend; MinIO is verification-only.--profile dogfood: brings up a second instance (studio B) plus its own Postgres and reverse proxy, for exercising federation between two peers locally.
3D thumbnail generation needs no profile. A headless three.js worker (Node and Chromium, shipped in the app image) renders it inside the app container, and has done since v0.6.0.
The Go binary is the runtime. Each release ships a single artifact:
- A multi-arch (
amd64+arm64) Docker image (ghcr.io/artist-alley-org/artist-alley, mirrored to Docker Hub), keyless-signed via Sigstore.
Native binaries, .deb / .rpm packages with a systemd unit, and a
Homebrew formula are planned for v0.22.0 and are required before
v1.0.0, tracked in
#242.
Test + release flow
Section titled “Test + release flow”Local development
Section titled “Local development”# Bring up the stackdocker compose up -d
# Tail logsdocker compose logs -f app web
# Run the Go tests (against a separate test database, reset each run)./scripts/test.sh
# Run the frontend type-checkdocker compose exec -T web sh -c 'cd /app && npm run check'After a Go binary change that isn’t picking up: docker compose up -d --build --force-recreate app. Without --force-recreate, compose can keep the old binary running.
Frontend edits hot-reload through Vite, which polls for file changes in this setup. After changing vite.config.ts or dependencies, recreate the web container: docker compose up -d --force-recreate web.
When Postgres misbehaves: docker compose logs postgres first. Migration failures, lock issues, role wipes: the Postgres log is the diagnostic, not the app log.
Release
Section titled “Release”feat/* → dev → main → tag → release.
- Working branches merge into
devvia PR (./scripts/test.shgreen required). dev → mainhappens at release boundaries via a PR merged with a merge commit.- Release tag (
v0.X.Y) onmaintriggers the GitHub Actions pipeline that builds the multi-arch Docker image, signs it with Sigstore, publishes to GHCR + Docker Hub, and posts the release notes. (Binaries and native packages are planned for v0.22.0 with #242, as a v1.0.0 prerequisite.) - CI and release jobs run on the self-hosted runner labelled
[artist-alley]. - Full procedure in
RELEASING.md.
Where things you’ll commonly look for live
Section titled “Where things you’ll commonly look for live”| Looking for | Path |
|---|---|
| HTTP routes and request/response shapes | app/api/openapi.yaml |
| The SQL that runs against Postgres | app/internal/<domain>/queries.sql |
| The schema you can query against | app/schema.sql |
| A specific table’s documentation | /developers/database/<table>/ |
| Migration history | app/internal/db/migrations/NNNNN_*.sql |
| Why we chose X over Y | /adr/: the ADR catalogue |
| Where a feature is on the roadmap | /roadmap/ |
| How a frontend component looks | web/src/lib/components/<area>/ |
| A locale string | web/src/lib/i18n/<locale>.json |
| Dev-stack containers | docker-compose.yml |
| Release procedure | RELEASING.md |
| Contribution flow | CONTRIBUTING.md + coding standards |