Aller au contenu

Développeurs

Artist Alley est open source, écrit principalement en Go (le backend se compile en un seul binaire) et en Svelte 5 (SPA frontend, intégrée via go:embed au moment de la publication). Il est distribué sous forme d’image Docker ; les artefacts de chaque version sont décrits dans la référence développeur. Le code source se trouve sur github.com/Artist-Alley-Org/artist-alley.

Le binaire Go est le runtime. Il prend en charge :

  • Le serveur HTTP sur /api/v1/... (OpenAPI d’abord ; spécification dans app/api/openapi.yaml). Les endpoints IIIF sont aussi servis sur /iiif/... pour les visionneuses externes.
  • L’état persistant sur Postgres via sqlc (requêtes dans app/internal/<domain>/queries.sql, Go généré dans queries.sql.go).
  • Une file de tâches pour les aperçus, l’ingestion, la recherche, le travail d’IA et les actions planifiées. La livraison de la fédération s’exécute sur sa propre file d’envoi (outbox).
  • Une abstraction de stockage avec des backends interchangeables : le système de fichiers par défaut, ou n’importe quel bucket compatible S3 avec AA_STORAGE_BACKEND=s3. Le profil Compose storage-s3 ne démarre MinIO que pour les tests locaux.
  • Le frontend intégré : les builds de publication (le build tag embed_web) embarquent la sortie du build SvelteKit avec go:embed et la servent depuis le même binaire. En développement, le binaire ne sert que l’API, IIIF et les vérifications de santé ; Vite sert le frontend sur localhost:5173 et transmet les requêtes /api et /iiif au backend, par défaut via le nginx de la stack Compose.

Aucun add-on n’est livré aujourd’hui. Les intégrations d’IA optionnelles (embeddings de texte, transcription et retouche d’images via un pont ComfyUI) font partie du binaire, sont désactivées par défaut et se connectent à des serveurs de modèles que l’opérateur exécute lui-même ou à des API de fournisseurs hébergées en externe que l’opérateur configure ; elles sont expérimentales. La recherche par image est partiellement construite, mais le sidecar CLIP dont elle dépend n’a pas encore de configuration prise en charge ; une version packagée est prévue avec les add-ons installables. Les miniatures 3D sont rendues dans le conteneur de l’application, avec Node et Chromium headless fournis par l’image, donc sans conteneur supplémentaire. Le registre d’add-ons de capacités est prévu pour la v0.17.0. Voir l’ADR 0034.

Le backend suit une organisation par domaine sous app/internal/<domain>/. Chaque domaine comprend généralement :

  • handler.go : les handlers HTTP et les adaptateurs entre les types générés depuis OpenAPI et le modèle du domaine.
  • queries.sql : les requêtes SQL gérées par sqlc.
  • queries.sql.go : le Go généré (ne le modifiez pas à la main ; régénérez-le avec ./scripts/generate.sh).
  • handler_test.go : des tests d’intégration contre un vrai Postgres (pas de mock de la base ; voir les standards de code).

Le frontend suit une organisation par route sous web/src/routes/, avec des composants partagés dans web/src/lib/components/. Les runes de Svelte 5 ($state, $derived, $effect) sont la primitive de gestion d’état. Elles fonctionnent dans les composants .svelte et dans les modules .svelte.js ou .svelte.ts, mais pas dans de simples fichiers .ts ; ce projet place l’état partagé en runes dans des modules .svelte.ts.

La version courte :

  1. Créez votre branche à partir de dev (la branche d’intégration ; main ne contient que du stable). Les noms de branche utilisent le préfixe feat/..., fix/... ou chore/....
  2. Exécutez ./scripts/test.sh jusqu’à ce qu’il passe avant d’ouvrir une PR. Il lance les tests d’intégration Go contre un vrai Postgres dans la stack de développement en cours d’exécution ; la vérification de types du frontend est une étape distincte (voir les standards de code).
  3. Les PR ciblent dev. Au moment d’une publication, dev rejoint main par un commit de merge, et main est la source des versions publiées.
  4. Messages de commit : <area>: <imperative summary> (par ex. assets: handle 0-byte uploads). Pas de coauteur Claude/IA.

La version complète se trouve dans les standards de code.

Quand une décision est assez importante pour devoir être expliquée des mois plus tard (topologie du backend, modèle de licence, posture de sécurité, forme de la monétisation), elle est consignée dans un Architecture Decision Record. Le catalogue des ADR est la réponse de référence à la question « pourquoi le projet est-il construit ainsi ? » ; la convention elle-même est l’ADR 0035.