Architecture
Artist Alley est volontairement petit. Un seul programme Go sert à la fois l’API et l’application web, Postgres conserve les enregistrements, et un backend de stockage conserve les fichiers. Vous pouvez placer votre propre reverse proxy devant pour le TLS. Des intégrations facultatives se connectent à des services extérieurs à l’application, comme un serveur de modèles d’IA. Cette page explique comment ces éléments s’articulent et pourquoi ils ont été choisis. Le guide d’installation explique comment l’exploiter.
Topologie de production
Section intitulée « Topologie de production »flowchart LR
user["Artiste / Relecteur / Opérateur"]
proxy["Reverse proxy<br/>nginx ou le vôtre, TLS"]
subgraph host["Hôte de l'application"]
app["Conteneur Artist Alley<br/>Binaire Go : API + application web intégrée<br/>plus outils média"]
fs[("Système de fichiers local<br/>backend de stockage fs")]
end
pg[("Postgres<br/>même hôte ou service séparé")]
s3[("Stockage objet compatible S3<br/>backend de stockage s3, peut être distant")]
ext["Services facultatifs<br/>fournisseurs d'IA, serveurs de modèles"]
user -->|"HTTPS, déploiements publics"| proxy
proxy -->|"transmet à"| app
user -.->|"HTTP, réseaux locaux ou de confiance"| app
app --> pg
app -->|"backend fs"| fs
app -.->|"ou backend s3"| s3
app -.->|"seulement si configuré"| ext
En clair : un déploiement public atteint l’application en HTTPS via un reverse proxy, tandis que le HTTP direct vers l’application est réservé aux réseaux locaux ou de confiance. L’application lit et écrit dans Postgres, qui peut tourner sur le même hôte ou comme service séparé. Elle stocke les fichiers dans un seul backend configuré : soit un répertoire sur l’hôte de l’application, soit un bucket compatible S3, qui peut se trouver n’importe où. Les intégrations d’IA facultatives appellent les services qu’un administrateur a configurés.
- Le binaire Go sert l’API JSON et l’application web SvelteKit, qui y est
compilée avec
go:embed: un seul programme sert donc les deux. Les builds de production utilisent le tag de compilationembed_web. Sans lui, en développement, le binaire ne sert que l’API, et le serveur de développement Vite sert le frontend et redirige les requêtes/apiet/iiifvers le backend. - L’image de conteneur empaquette ce binaire avec les outils en ligne de commande qu’il exécute pour générer les aperçus et les miniatures : ffmpeg, ImageMagick, Ghostscript, Poppler, librsvg et unar, ainsi que Node et un Chromium headless pour le rendu des aperçus 3D. Ils sont livrés dans l’image ; vous ne les exploitez pas comme des services séparés.
- Postgres conserve tous les enregistrements qu’Artist Alley gère :
assets, champs de métadonnées et leurs valeurs, posts, membres,
collections, commentaires, mentions « j’aime », sessions, audit et
paramètres d’installation. Il nécessite l’extension pgvector
(Postgres). Les migrations se
trouvent dans
app/internal/db/migrations/, sont compilées dans le binaire et s’exécutent à son démarrage. - Le stockage de fichiers conserve les octets, et il est adressé par
le contenu : chaque fichier stocké a pour clé son SHA-256, si bien que
les mêmes octets ne sont stockés qu’une seule fois, et les fichiers sont
organisés par hash plutôt que dans des dossiers de projet. Vous
configurez l’un des deux backends :
fs: un répertoire sur l’hôte de l’application (monté dans le conteneur)s3: tout service de stockage doté d’une API compatible S3, local ou distant
- Un reverse proxy comme nginx est facultatif sur un réseau local ou de confiance. Le binaire sert du HTTP simple et ne termine pas lui-même le TLS ; un déploiement public doit donc se placer derrière un proxy qui fournit le HTTPS, comme celui que vous exploitez déjà.
Postgres et le stockage de fichiers sont tous deux des états durables, et aucun n’est utile sans l’autre : la base de données sait quel hash appartient à quel asset, et le stockage conserve les octets. Une sauvegarde que vous pouvez restaurer comporte trois parties : la base de données, les fichiers stockés et les deux clés de l’instance (Sauvegarde).
API pilotée par le contrat
Section intitulée « API pilotée par le contrat »L’API JSON est définie dans
app/api/openapi.yaml.
Ce fichier est le contrat : les types du serveur et les interfaces des
handlers en sont générés par oapi-codegen, et le frontend génère ses
types TypeScript à partir du même fichier avec openapi-typescript.
Modifier l’API publique, c’est d’abord modifier la spécification. Un handler dont la signature Go s’écarte de l’interface générée ne compile pas. En CI, le job du frontend régénère les types TypeScript et vérifie les types de l’application par rapport à eux, et un job distinct de détection de dérive du code généré relance les générateurs et échoue si le code généré versionné est périmé. Cela détecte la dérive des types entre la spécification, le serveur et le frontend. Cela ne prouve pas comment l’API se comporte à l’exécution ; c’est le rôle des suites de tests.
La référence générée se trouve dans la référence de l’API et est reconstruite à partir de la même spécification à chaque build du site.
Le schéma Postgres est déclaré dans
app/internal/db/migrations/*.sql
et documenté table par table dans le schéma de la base de données.
Les migrations font foi : la base de référence de la v0.1.0
(00001_baseline_v0_1.sql) plus les migrations ajoutées depuis. Selon
l’ADR 0046, les
migrations s’ajoutent librement pendant la bêta, et le plan est de les
fusionner dans une nouvelle base de référence à la v1.0.0.
app/schema.sql est produit à partir des migrations : on les exécute sur
une base vide et on exporte le schéma obtenu. sqlc lit ce fichier
versionné pour vérifier les types des requêtes Go lors de la génération du
code ; une requête qui ne correspond plus à ses tables fait donc échouer la
génération. Le job de détection de dérive de la CI régénère le code à partir
du schema.sql versionné et échoue si le code généré versionné est périmé.
Il ne reconstruit pas schema.sql à partir des migrations : il ne peut donc
pas vous dire si les deux divergent ; régénérer le fichier fait partie de
l’ajout d’une migration, et son en-tête donne la marche à suivre.
Configuration et system_config
Section intitulée « Configuration et system_config »Il y a deux niveaux :
- La configuration du processus (connexion à la base de données, clés, backend de stockage, adresse d’écoute, journalisation) vient des variables d’environnement ; voir la référence de configuration du guide d’installation.
- Les paramètres de toute l’installation (nom du site, SMTP,
fournisseurs d’authentification, fournisseurs d’IA, polices de la marque,
thèmes) sont stockés sous forme de lignes de type JSON dans la table
system_config. Ils se modifient par l’interface d’administration et sont exposés par l’API/admin/system/*. La cléappearance, par exemple, pilote le sélecteur d’emplacements de polices propre à l’installation.
Les paramètres d’installation ne sont jamais fédérés : ils restent sur l’instance à laquelle ils appartiennent. Les profils d’utilisateur indiquent de quel serveur chaque utilisateur provient.
Pourquoi ces choix
Section intitulée « Pourquoi ces choix »- Go pour le serveur : le serveur d’API, les migrations de la base de
données et l’application web intégrée sont compilés en un seul binaire,
qui est le point d’entrée du conteneur (
/app/aa). Le transport en temps réel des sessions de relecture en direct prévues n’est pas encore décidé. - SvelteKit pour l’application web : avec
adapter-static, le résultat du build est constitué de simples fichiers ; il n’y a donc pas de serveur d’interface distinct à déployer ni à maintenir en marche. Ses types viennent de la même spécification que ceux du serveur, comme décrit dans API pilotée par le contrat. - Postgres uniquement : les enregistrements relationnels, la recherche
plein texte et les vecteurs partagent une seule base de données ; les
seuls services obligatoires sont donc l’application et Postgres, et il
n’y a ni service de recherche, ni base vectorielle, ni serveur de cache
séparés à exploiter et à sauvegarder. La recherche plein texte repose sur
une colonne
tsvectorque des triggers reconstruisent à chaque écriture, et pgvector, dans la même base, stocke les embeddings que produisent les intégrations d’IA facultatives. Ces intégrations sont expérimentales, se connectent à des serveurs de modèles ou à des API de fournisseurs qu’un administrateur configure, et ne livrent aucun modèle. La recherche par image est en partie réalisée dans la même base, 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 modules complémentaires installables. go:embedpour l’application web : les ressources web sont intégrées au même binaire que l’API ; l’interface et le serveur sont donc toujours déployés ensemble, dans la même version, et il n’y a pas de déploiement de ressources statiques à garder synchronisé.- Stockage adressé par le contenu : envoyer deux fois les mêmes octets ne les stocke qu’une fois, et vous pouvez vérifier n’importe quel fichier en le re-hachant et en comparant le résultat à sa clé. Le compromis est celui décrit plus haut : le stockage n’a de sens qu’avec la base de données ; un déplacement ou une restauration nécessite donc les trois parties d’une sauvegarde, comme l’explique le guide de sauvegarde.
Pour le raisonnement derrière chaque grand choix, consultez les décisions d’architecture.