Aller au contenu

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.

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 compilation embed_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 /api et /iiif vers 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).

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.

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.

  • 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 tsvector que 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:embed pour 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.