Aller au contenu
alan.salmon
Tous les projets
v1 (sur 4 versions prévues) · 2026

Opi!

Site d'entraînement au finnois : il présente le contenu nouveau, interroge par des exercices tapés au clavier, planifiés par répétition espacée, et corrige en montrant la forme attendue et la règle. Il tourne sur un cluster Kubernetes monté dans mon homelab, mis à jour automatiquement à chaque merge.

Année
2026
  • Python
  • Flask
  • Kubernetes
  • k3s
  • Terraform
  • Proxmox
Accueil d'Opi! : la séance de révision du jour, sur fond d'aurore boréale

01 · Contexte

Le défi

Projet personnel né d'une petite application Flask de conjugaison, devenu une vraie plateforme pensée comme en production. Opi! fait trois choses : il présente le contenu nouveau (verbes, mots, expressions) sur une fiche de découverte, il interroge par des exercices tapés au clavier dont le rythme est planifié par répétition espacée (FSRS), et il corrige en montrant la forme attendue, les lettres qui diffèrent et la règle. Chaque session mélange les révisions dues, les exercices que débloquent les compétences de grammaire et les nouveautés du jour, et la Bibliothèque permet de parcourir tout le contenu. Ce contenu est la contrainte centrale : il vit dans des fichiers YAML relus à la main, seul ce que j'ai validé arrive dans les exercices, et le code n'invente aucune forme finnoise. Usage personnel, non public, déployé comme en production.

02 · Architecture

Comment c'est construit

Schéma d'architecture d'Opi! : le navigateur, le front (React, nginx), api avec Redis, puis lexicon et srs, chacun avec sa base dans une instance Postgres, et le dossier data/ importé dans lexicon
Quatre services qui ne se parlent qu'en HTTP JSON : api orchestre, lexicon et srs décident

Les points clés

  • Contenu finnois versionné dans Git et validé à la main : le code n'invente aucune forme
  • Quatre services (front React, api, lexicon, srs) qui ne communiquent qu'en HTTP JSON : aucun ne lit la base d'un autre
  • Révisions planifiées par la bibliothèque FSRS (répétition espacée), sans réimplémenter l'algorithme
  • Infrastructure décrite en code (Terraform) : trois machines virtuelles et un cluster k3s recréables à l'identique
  • Livraison automatique : un merge sur main reconstruit les images, les range dans un registre privé Harbor, et Argo CD met le cluster à jour
  • Site accessible seulement depuis le réseau privé (Tailscale), avec sauvegarde de la progression chaque soir, restaurée et testée

03 · En images

Galerie

  • Écran de session : le tableau du présent du verbe mennä, avec l'infinitif et trois personnes remplis, la quatrième en cours de saisie, et la barre de progression en haut sur un ciel d'aurore boréale
    Une session en cours : le tableau du présent d'un verbe, à remplir forme par forme
  • Page Bibliothèque : champ de recherche, filtres par lot, type et tag, et dix tuiles d'adjectifs de couleur, chacune avec une pastille de sa couleur
    La Bibliothèque, filtrée par tag : les couleurs, chacune avec sa pastille
  • Page Compétences : liste de points de grammaire avec leur règle, leurs exercices et leur nombre de cartes, trois d'entre eux débloqués
    Les compétences de grammaire, que l'on débloque une à une (état de démonstration)
  • Schéma de la composition d'une session : les révisions dues, les exercices débloqués et les notions en alternance, puis les nouveautés avec fiche, QCM et cartes
    Comment une session se compose : révisions dues, exercices débloqués, notions, puis nouveautés
  • Schéma montrant comment un verbe, un nom ou une notion donne ses cartes, chacune avec les compétences qu'elle exige
    D'un élément à ses cartes, et les compétences que chaque carte exige
  • Schéma du circuit du contenu : proposition d'un lot en brouillon, contrôles automatiques, relecture, import, service par lexicon, révision et signalement
    Le circuit du contenu : de la proposition en brouillon à la validation à la main, puis à la révision
  • Schéma détaillé de l'architecture : le navigateur, le front, api et Redis, lexicon et srs avec leurs bases Postgres, le dossier data/ et les règles qui tiennent l'ensemble
    L'architecture en détail : les ports, les règles qui tiennent l'ensemble et les flux entre les services
  • Schéma de la connexion : les deux couches de protection, le mot de passe, le cookie de session et les contrôles de chaque requête
    Connexion et sécurité : deux couches, un cookie de session et des contrôles à chaque requête
  • Schéma séquentiel d'une carte, de la question préparée par api à la note enregistrée par srs
    Une carte de bout en bout : la question, la réponse corrigée, la note enregistrée
  • Schéma des étapes de session : un extrait de réponse JSON de l'API, la boucle entre le front et api, et un tableau reliant chaque type d'étape à son écran et à sa requête
    Ce que renvoie l'API à chaque étape de session, et l'écran du front qui s'en charge
  • Schéma du cycle d'une carte dans FSRS : entrée dans le cycle, apprentissage, révision et réapprentissage
    La vie d'une carte dans FSRS : apprentissage, révision et réapprentissage
  • Schéma de la version 0 d'Opi! : web, lexicon, srs, Redis et deux bases Postgres sous docker compose, et ce que chaque pull request de la v1 modifie
    La première version, en local sous docker compose, et ce que change chaque pull request de la v1
  • Schéma de la livraison : le job de GitHub sur main, Harbor sur le NAS, le commit du bot, puis les vagues de synchronisation d'Argo CD dans le cluster
    De la fusion sur main au cluster : images reconstruites, poussées sur Harbor, puis synchronisation d'Argo CD par vagues
  • Schéma du registre d'images : le NAS Synology avec Harbor et ses composants, le tailnet pour la CI et l'interface d'administration, le réseau local pour les trois nœuds k3s
    Le registre d'images Harbor sur le NAS, joint par deux chemins : le tailnet pour la CI, le réseau local pour les nœuds
  • Schéma séquentiel de l'identité de la CI : le job demande un jeton à GitHub, Tailscale le vérifie, le runner rejoint le tailnet et pousse sur Harbor ; le contenu du jeton et les cas refusés
    Comment la CI entre dans le tailnet sans secret : un jeton OIDC de GitHub vérifié par Tailscale
  • Schéma de la sauvegarde : le CronJob de 22 h, les cinq étapes du Job, le partage NFS du NAS, puis le contrôle sans risque et la restauration
    La sauvegarde nocturne de la base srs sur le NAS, et les deux façons de la contrôler ou de la restaurer
  • Schéma de la supervision : Prometheus et ses cibles dans le namespace, les deux règles d'alerte sur la sauvegarde, l'interface réservée au tailnet et ce qui est prévu en v2
    La supervision : Prometheus lit les services, deux règles surveillent la sauvegarde, l'interface reste sur le tailnet

Cliquer sur une image l'ouvre en plein écran, avec navigation entre les captures.

04 · Bilan

Ce que j'en retire

Décrire une infrastructure en code (Terraform) : les machines se recréent à l'identique, et Argo CD remet le cluster dans l'état décrit dans Git. Un merge suffit à déployer.