Référence développeur
Le code source d’Artist Alley se trouve sur github.com/Artist-Alley-Org/artist-alley. Cette page est la carte : l’organisation de premier niveau, le motif par domaine du backend, l’organisation du frontend, les éléments d’infrastructure, et le chemin d’un changement depuis une modification locale jusqu’à une publication.
Organisation de premier niveau
Section intitulée « Organisation de premier niveau »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 procedureLe frontend intégré n’est pas conservé dans le dépôt : le build de l’image
copie la sortie de SvelteKit dans app/internal/http/static_assets/
avant de compiler le binaire.
Organisation par domaine du backend
Section intitulée « Organisation par domaine du backend »Le backend Go suit une organisation par domaine sous app/internal/<domain>/. Chaque domaine possède un champ de capacité et est autonome.
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 handlerQuelques-uns des principaux domaines (app/internal/ en contient beaucoup d’autres, dont federation, search, visibility, notifications, email, licensing et iiif) :
| Domaine | Ce qu’il possède |
|---|---|
assets | L’entité asset centrale, son cycle de vie, les métadonnées de fichier |
assettype | La table de référence des types d’asset |
metadata | Définitions de champs, valeurs de champs des assets, historique |
collections | Collections de posts, avec ACL |
posts | Posts enveloppant un ou plusieurs assets |
social | Commentaires, mentions « j’aime » |
auth | Sessions, connexion, gestion des mots de passe |
acls | Vérifications de listes de contrôle d’accès par ligne |
users, teams | Surfaces d’identité |
audit | Registre des événements d’audit |
cache | Registre de cache en mémoire avec invalidation inter-domaines |
config, sysconfig | Surfaces de configuration système |
db | Migrations et utilitaires de base de données de bas niveau |
http | Amorçage du serveur HTTP et middlewares |
sitetext | Surcharges par l’opérateur des chaînes de l’interface, superposées au catalogue en.json livré |
jobs | File de tâches asynchrones |
openapi | Types générés du serveur strict |
preview | Pipeline de génération de miniatures et d’aperçus |
setup | Endpoints d’installation du premier lancement, inactifs dès qu’un admin existe (une installation normale en crée un au démarrage) |
storage | Backend de stockage interchangeable (fs / S3) |
workflow | Machine à états des assets et des posts |
abr, brushpacks | Import de pinceaux Photoshop .abr et packs de pinceaux pour l’outil de croquis |
logging | Configuration du journal structuré (slog) pour tout le processus ; l’expédition des journaux est prévue |
Tout s’exécute dans un seul processus : aucun domaine n’en appelle un autre via HTTP. Les appels entre domaines passent par :
- De petites dépendances ciblées quand un domaine a besoin d’une capacité d’un autre (par ex. les handlers qui émettent des événements reçoivent un
*audit.Recorder, et certains déclarent une interface plus étroite par-dessus). - Le registre de cache (
cache.Registry) pour l’invalidation entre packages. Il utilise LISTEN/NOTIFY de Postgres, si bien que plusieurs processus d’application partageant une même base abandonnent ensemble les entrées obsolètes ; il ne synchronise pas les instances fédérées.
Ce que cette organisation cherche à éviter : qu’un domaine importe directement le dépôt ou les types de requêtes d’un autre domaine. Ce couplage est précisément ce que l’organisation par domaine est censée empêcher ; les rares endroits qui lisent encore les requêtes d’un autre domaine (du code d’aperçu et de service de fichiers lit les requêtes de assets) sont des exceptions, pas la règle.
Organisation du frontend
Section intitulée « Organisation du frontend »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 helpersLes runes ($state, $derived, $effect) fonctionnent dans les composants .svelte et dans les modules .svelte.js ou .svelte.ts ; dans un simple fichier .ts, elles ne sont pas compilées. L’état partagé en runes va dans des modules .svelte.ts ; voir les standards de code.
Les types générés sont actualisés par npm run generate:api après chaque modification de openapi.yaml. Le fichier de schéma est ignoré par git (gitignored), donc une copie obsolète n’affecte que vos vérifications locales : la CI le génère à neuf à partir de openapi.yaml avant de vérifier les types du frontend avec svelte-check.
Infrastructure
Section intitulée « 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)La stack de développement se lance avec docker compose up. Profils optionnels :
--profile storage-s3: exécute MinIO pour tester le backend S3. Le développement quotidien utilise le backend système de fichiers ; MinIO ne sert qu’à la vérification.--profile dogfood: démarre une seconde instance (studio B), avec son propre Postgres et son propre reverse proxy, pour exercer la fédération entre deux pairs en local.
La génération de miniatures 3D n’a besoin d’aucun profil. Un worker three.js headless (Node et Chromium, fournis dans l’image de l’application) la rend à l’intérieur du conteneur de l’application, et ce depuis la v0.6.0.
Le binaire Go est le runtime. Chaque version livre un seul artefact :
- Une image Docker multi-architecture (
amd64+arm64) (ghcr.io/artist-alley-org/artist-alley, répliquée sur Docker Hub), signée sans clé (keyless) via Sigstore.
Des binaires natifs, des paquets .deb / .rpm avec une unité systemd et
une formule Homebrew sont prévus pour la v0.22.0 et sont requis avant la
v1.0.0, suivis dans
#242.
Flux de test et de publication
Section intitulée « Flux de test et de publication »Développement local
Section intitulée « Développement local »# 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'Après une modification du binaire Go qui n’est pas prise en compte : docker compose up -d --build --force-recreate app. Sans --force-recreate, compose peut continuer à exécuter l’ancien binaire.
Les modifications du frontend se rechargent à chaud via Vite, qui interroge périodiquement (polling) les changements de fichiers dans cette configuration. Après avoir modifié vite.config.ts ou les dépendances, recréez le conteneur web : docker compose up -d --force-recreate web.
Quand Postgres se comporte mal : docker compose logs postgres d’abord. Échecs de migration, problèmes de verrous, rôles effacés : le diagnostic se trouve dans le journal de Postgres, pas dans celui de l’application.
Publication
Section intitulée « Publication »feat/* → dev → main → tag → publication.
- Les branches de travail fusionnent dans
devvia une PR (./scripts/test.shdoit passer). dev → maina lieu aux jalons de publication via une PR fusionnée avec un merge commit.- Le tag de version (
v0.X.Y) surmaindéclenche le pipeline GitHub Actions qui construit l’image Docker multi-architecture, la signe avec Sigstore, la publie sur GHCR et Docker Hub, et poste les notes de version. (Les binaires et paquets natifs sont prévus pour la v0.22.0 avec #242, comme prérequis de la v1.0.0.) - Les jobs de CI et de publication s’exécutent sur le runner auto-hébergé portant le label
[artist-alley]. - Procédure complète dans
RELEASING.md.
Où se trouvent les choses que vous cherchez le plus souvent
Section intitulée « Où se trouvent les choses que vous cherchez le plus souvent »| Ce que vous cherchez | Chemin |
|---|---|
| Routes HTTP et formes des requêtes/réponses | app/api/openapi.yaml |
| Le SQL exécuté sur Postgres | app/internal/<domain>/queries.sql |
| Le schéma sur lequel vous pouvez écrire des requêtes | app/schema.sql |
| La documentation d’une table précise | /developers/database/<table>/ |
| L’historique des migrations | app/internal/db/migrations/NNNNN_*.sql |
| Pourquoi nous avons choisi X plutôt que Y | /adr/ : le catalogue des ADR |
| Où en est une fonctionnalité sur la feuille de route | /roadmap/ (en anglais) |
| À quoi ressemble un composant du frontend | web/src/lib/components/<area>/ |
| Une chaîne de langue | web/src/lib/i18n/<locale>.json |
| Les conteneurs de la stack de développement | docker-compose.yml |
| La procédure de publication | RELEASING.md |
| Le flux de contribution | CONTRIBUTING.md + standards de code |