Skip to content

Architecture

Artist Alley is small on purpose. One Go program serves both the API and the web app, Postgres holds the records, and a storage backend holds the files. You can put your own reverse proxy in front for TLS. Optional integrations connect to services outside the app, such as an AI model server. This page explains how those pieces relate and why they were chosen. The install guide covers running it.

flowchart LR
  user[Artist / Reviewer / Operator]
  proxy[Reverse proxy<br/>nginx or your own, TLS]
  subgraph host[App host]
    app[Artist Alley container<br/>Go binary: API + embedded web app<br/>plus media tools]
    fs[(Local filesystem<br/>storage backend fs)]
  end
  pg[(Postgres<br/>same host or a separate service)]
  s3[(S3-compatible object storage<br/>storage backend s3, can be remote)]
  ext[Optional services<br/>AI providers, model servers]
  user -->|HTTPS, public deployments| proxy
  proxy -->|forwards to| app
  user -.->|HTTP, local or trusted networks| app
  app --> pg
  app -->|fs backend| fs
  app -.->|or s3 backend| s3
  app -.->|only if configured| ext

In words: a public deployment reaches the app over HTTPS through a reverse proxy, while direct HTTP to the app is for local or trusted networks. The app reads and writes Postgres, which can run on the same host or as a separate service. It stores files in one configured backend: either a directory on the app host or an S3-compatible bucket, which can be anywhere. Optional AI integrations call the services an admin has configured.

  • The Go binary serves the JSON API and the SvelteKit web app, which is compiled into it with go:embed, so one program serves both. Production builds use the embed_web build tag. Without it, in development, the binary serves only the API, and the Vite dev server serves the frontend and proxies /api and /iiif requests to the backend.
  • The container image packages that binary with the command-line tools it runs to build previews and thumbnails: ffmpeg, ImageMagick, Ghostscript, Poppler, librsvg and unar, plus Node and a headless Chromium for rendering 3D previews. They ship inside the image; you don’t run them as separate services.
  • Postgres holds every record Artist Alley owns: assets, metadata fields and their values, posts, members, collections, comments, likes, sessions, audit, and install settings. It needs the pgvector extension (Postgres). Migrations live in app/internal/db/migrations/, are compiled into the binary, and run when it starts.
  • File storage holds the bytes, and it is content-addressed: every stored file is keyed by its SHA-256, so the same bytes are only ever stored once, and files are laid out by hash rather than in project folders. You configure one of two backends:
    • fs: a directory on the app host (mounted into the container)
    • s3: any storage service with an S3-compatible API, local or remote
  • A reverse proxy such as nginx is optional on a local or trusted network. The binary serves plain HTTP and doesn’t terminate TLS itself, so a public deployment should sit behind a proxy that provides HTTPS, such as the one you already run.

Postgres and the file storage are both durable state, and neither is useful without the other: the database knows which hash belongs to which asset, and the storage holds the bytes. A backup you can restore has three parts: the database, the stored files and the instance’s two keys (Backup).

The JSON API is defined in app/api/openapi.yaml. That file is the contract: the server’s types and handler interfaces are generated from it by oapi-codegen, and the frontend generates its TypeScript types from the same file with openapi-typescript.

Changing the public API means changing the spec first. A handler whose Go signature drifts from the generated interface won’t compile. In CI, the frontend job regenerates the TypeScript types and type-checks the app against them, and a separate codegen-drift job re-runs the generators and fails if the committed generated code is stale. That catches type drift between the spec, the server and the frontend. It doesn’t prove how the API behaves at runtime; that’s what the test suites are for.

The rendered reference lives at API reference and is rebuilt from the same spec on every site build.

The Postgres schema is declared in app/internal/db/migrations/*.sql and documented table by table at Database schema. The migrations are the source of truth: the v0.1.0 baseline (00001_baseline_v0_1.sql) plus the migrations added after it. Per ADR 0046, migrations are appended freely during the beta, and the plan is to fold them into a new baseline at v1.0.0.

app/schema.sql is produced from the migrations: run them against an empty database and dump the resulting schema. sqlc reads that checked-in file to type-check the Go queries when code is generated, so a query that no longer matches its tables fails generation. CI’s codegen-drift job regenerates code against the checked-in schema.sql and fails if the committed generated code is stale. It does not rebuild schema.sql from the migrations, so it can’t tell you whether the two disagree; regenerating the file is part of adding a migration, and its header gives the steps.

There are two layers:

  • Process config (database connection, keys, storage backend, listen address, logging) comes from environment variables; see the install guide configuration reference.
  • Install-wide settings (site name, SMTP, auth providers, AI providers, brand fonts, themes) are stored as JSON-typed rows in the system_config table. They are changed through the admin UI and exposed through the /admin/system/* API. The appearance key, for example, drives the per-install font slot picker.

Install settings never federate: they stay on the instance they belong to. User profiles record which server each user came from.

  • Go for the server: the API server, the database migrations and the embedded web app compile into one binary, which is the container’s entry point (/app/aa). The real-time transport for planned live review sessions is not decided yet.
  • SvelteKit for the web app: with adapter-static the build output is plain files, so there is no separate UI server to deploy or keep running. Its types come from the same spec as the server’s, as described under Contract-first API.
  • Postgres only: relational records, full-text search and vectors share one database, so the only mandatory services are the app and Postgres, and there is no separate search service, vector store or cache server to run and back up. Full-text search is a tsvector column that triggers rebuild on writes, and pgvector, in the same database, stores the embeddings the optional AI integrations produce. Those integrations are experimental, connect to model servers or provider APIs an admin configures, and ship no models. Search by image is partly built in the same database, but the CLIP sidecar it depends on has no supported setup yet; a packaged version is planned with installable add-ons.
  • go:embed for the web app: the web assets are built into the same binary as the API, so the UI and the server always roll out together at the same version, and there is no static-asset deployment to keep in step.
  • Content-addressed storage: uploading the same bytes twice stores them once, and you can check any file by re-hashing it against its key. The tradeoff is the one described above: the storage only makes sense together with the database, so a move or a restore takes all three parts of a backup, as the backup guide describes.

For the rationale behind each big call, see Architecture Decisions.