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.
- Pour le détail des dossiers du projet, consultez la référence développeur.
- Pour un aperçu des tables de la base de données, consultez le schéma de la base de données.
- Tous les contributeurs doivent respecter les standards de code.
- Les surfaces sensibles et le modèle de menaces du projet sont documentés dans La sécurité dans Artist Alley.
Ce que contient le binaire
Section intitulée « Ce que contient le binaire »Le binaire Go est le runtime. Il prend en charge :
- Le serveur HTTP sur
/api/v1/...(OpenAPI d’abord ; spécification dansapp/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é dansqueries.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 Composestorage-s3ne 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 avecgo:embedet 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 surlocalhost:5173et transmet les requêtes/apiet/iiifau 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.
Comment le code est organisé
Section intitulée « Comment le code est organisé »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.
Contribuer
Section intitulée « Contribuer »La version courte :
- Créez votre branche à partir de
dev(la branche d’intégration ;mainne contient que du stable). Les noms de branche utilisent le préfixefeat/...,fix/...ouchore/.... - Exécutez
./scripts/test.shjusqu’à 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). - Les PR ciblent
dev. Au moment d’une publication,devrejointmainpar un commit de merge, etmainest la source des versions publiées. - 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.
Décisions d’architecture
Section intitulée « Décisions d’architecture »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.