Aller au contenu

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.

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

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

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 handler

Quelques-uns des principaux domaines (app/internal/ en contient beaucoup d’autres, dont federation, search, visibility, notifications, email, licensing et iiif) :

DomaineCe qu’il possède
assetsL’entité asset centrale, son cycle de vie, les métadonnées de fichier
assettypeLa table de référence des types d’asset
metadataDéfinitions de champs, valeurs de champs des assets, historique
collectionsCollections de posts, avec ACL
postsPosts enveloppant un ou plusieurs assets
socialCommentaires, mentions « j’aime »
authSessions, connexion, gestion des mots de passe
aclsVérifications de listes de contrôle d’accès par ligne
users, teamsSurfaces d’identité
auditRegistre des événements d’audit
cacheRegistre de cache en mémoire avec invalidation inter-domaines
config, sysconfigSurfaces de configuration système
dbMigrations et utilitaires de base de données de bas niveau
httpAmorçage du serveur HTTP et middlewares
sitetextSurcharges par l’opérateur des chaînes de l’interface, superposées au catalogue en.json livré
jobsFile de tâches asynchrones
openapiTypes générés du serveur strict
previewPipeline de génération de miniatures et d’aperçus
setupEndpoints d’installation du premier lancement, inactifs dès qu’un admin existe (une installation normale en crée un au démarrage)
storageBackend de stockage interchangeable (fs / S3)
workflowMachine à états des assets et des posts
abr, brushpacksImport de pinceaux Photoshop .abr et packs de pinceaux pour l’outil de croquis
loggingConfiguration 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.

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

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

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.

Fenêtre de terminal
# 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'

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.

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

  • Les branches de travail fusionnent dans dev via une PR (./scripts/test.sh doit passer).
  • dev → main a lieu aux jalons de publication via une PR fusionnée avec un merge commit.
  • Le tag de version (v0.X.Y) sur main dé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 cherchezChemin
Routes HTTP et formes des requêtes/réponsesapp/api/openapi.yaml
Le SQL exécuté sur Postgresapp/internal/<domain>/queries.sql
Le schéma sur lequel vous pouvez écrire des requêtesapp/schema.sql
La documentation d’une table précise/developers/database/<table>/
L’historique des migrationsapp/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 frontendweb/src/lib/components/<area>/
Une chaîne de langueweb/src/lib/i18n/<locale>.json
Les conteneurs de la stack de développementdocker-compose.yml
La procédure de publicationRELEASING.md
Le flux de contributionCONTRIBUTING.md + standards de code