Skip to content

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.

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

The 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.

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 handler

Some of the main domains (app/internal/ holds many more, including federation, search, visibility, notifications, email, licensing and iiif):

DomainWhat it owns
assetsCore asset entity, lifecycle, file metadata
assettypeAsset-type lookup table
metadataField definitions, asset field values, history
collectionsCollections of posts, with ACLs
postsPosts wrapping one or many assets
socialComments, likes
authSessions, login, password handling
aclsPer-row access control list checks
users, teamsIdentity surfaces
auditAudit-event ledger
cacheIn-memory cache registry with cross-domain invalidation
config, sysconfigSystem configuration surfaces
dbMigrations + low-level DB helpers
httpHTTP server bootstrap + middleware
sitetextOperator overrides for UI strings, layered over the shipped en.json catalogue
jobsAsync job queue
openapiGenerated strict-server types
previewThumbnail / preview generation pipeline
setupFirst-run installer endpoints, inactive once an admin exists (a normal install creates one at boot)
storagePluggable storage backend (fs / S3)
workflowAsset / post state machine
abr, brushpacksPhotoshop .abr brush import + brush packs for the sketch tool
loggingProcess-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.

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

Runes ($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.

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.

Terminal window
# 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'

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.

feat/* → dev → main → tag → release.

  • Working branches merge into dev via PR (./scripts/test.sh green required).
  • dev → main happens at release boundaries via a PR merged with a merge commit.
  • Release tag (v0.X.Y) on main triggers 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 forPath
HTTP routes and request/response shapesapp/api/openapi.yaml
The SQL that runs against Postgresapp/internal/<domain>/queries.sql
The schema you can query againstapp/schema.sql
A specific table’s documentation/developers/database/<table>/
Migration historyapp/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 looksweb/src/lib/components/<area>/
A locale stringweb/src/lib/i18n/<locale>.json
Dev-stack containersdocker-compose.yml
Release procedureRELEASING.md
Contribution flowCONTRIBUTING.md + coding standards