Skip to content
alan.salmon
All projects
v1 (of 4 planned versions) · 2026

Opi!

A Finnish training site: it introduces new content, tests with typed exercises scheduled by spaced repetition, and corrects by showing the expected form and the rule. It runs on a Kubernetes cluster built in my homelab, updated automatically on every merge.

Year
2026
  • Python
  • Flask
  • Kubernetes
  • k3s
  • Terraform
  • Proxmox
Opi! home page: today's review session, over a northern-lights background

01 · Context

The challenge

Personal project that started as a small Flask conjugation app and grew into a real platform, designed as if in production. Opi! does three things: it introduces new content (verbs, words, expressions) on a discovery sheet, it tests with typed exercises whose timing is planned by spaced repetition (FSRS), and it corrects by showing the expected form, the letters that differ and the rule. Each session mixes the reviews that are due, the exercises unlocked by the grammar skills and the day's new items, and the Library lets me browse all the content. That content is the central constraint: it lives in YAML files that I review by hand, only what I have approved reaches the exercises, and the code never invents a Finnish form. Personal use, not public, deployed as if in production.

02 · Architecture

How it's built

Opi! architecture diagram: the browser, the front end (React, nginx), api with Redis, then lexicon and srs, each with its own database in one Postgres instance, and the data/ folder imported into lexicon
Four services that only talk over JSON HTTP: api orchestrates, lexicon and srs decide

Key points

  • Finnish content versioned in Git and reviewed by hand: the code never invents a form
  • Four services (React front end, api, lexicon, srs) that only talk over JSON HTTP: none reads another one's database
  • Reviews scheduled by the FSRS library (spaced repetition), without reimplementing the algorithm
  • Infrastructure described as code (Terraform): three virtual machines and a k3s cluster that can be recreated identically
  • Automated delivery: a merge on main rebuilds the images, stores them in a private Harbor registry, and Argo CD updates the cluster
  • Site reachable only from the private network (Tailscale), with the progress backed up every night, restored and tested

03 · In pictures

Gallery

  • Session screen: the present-tense table of the verb mennä, with the infinitive and three persons filled in, the fourth being typed, and the progress bar at the top over a northern-lights sky
    A session in progress: the present-tense table of a verb, to fill in form by form
  • Library page: search field, filters by lot, type and tag, and ten tiles of colour adjectives, each with a swatch of its colour
    The Library, filtered by tag: the colours, each with its swatch
  • Skills page: list of grammar points with their rule, their exercises and their number of cards, three of them unlocked
    The grammar skills, unlocked one by one (demo state)
  • Diagram of how a session is composed: due reviews, unlocked exercises and notions in alternation, then new items with sheet, quiz and cards
    How a session is put together: due reviews, unlocked exercises, notions, then new items
  • Diagram showing how a verb, a noun or a notion gives its cards, each with the skills it requires
    From an item to its cards, and the skills each card requires
  • Diagram of the content circuit: a lot proposed as a draft, automatic checks, review, import, serving by lexicon, review and reporting
    The content circuit: from a draft proposal to hand validation, then to review
  • Detailed architecture diagram: the browser, the front end, api and Redis, lexicon and srs with their Postgres databases, the data/ folder and the rules that hold it together
    The architecture in detail: the ports, the rules that hold it together and the flows between services
  • Diagram of the login: the two layers of protection, the password, the session cookie and the checks on every request
    Login and security: two layers, a session cookie and checks on every request
  • Sequence diagram of one card, from the question prepared by api to the rating saved by srs
    A card from end to end: the question, the corrected answer, the saved rating
  • Diagram of session steps: an excerpt of the API's JSON response, the loop between the front end and api, and a table linking each step type to its screen and its request
    What the API returns at each session step, and the front-end screen that handles it
  • Diagram of a card's cycle in FSRS: entering the cycle, learning, review and relearning
    A card's life in FSRS: learning, review and relearning
  • Diagram of Opi! version 0: web, lexicon, srs, Redis and two Postgres databases under docker compose, and what each v1 pull request changes
    The first version, local under docker compose, and what each v1 pull request changes
  • Delivery diagram: the GitHub job on main, Harbor on the NAS, the bot commit, then Argo CD sync waves in the cluster
    From merge on main to the cluster: images rebuilt, pushed to Harbor, then Argo CD syncing in waves
  • Image registry diagram: the Synology NAS with Harbor and its components, the tailnet for CI and the admin UI, the local network for the three k3s nodes
    The Harbor image registry on the NAS, reached by two paths: the tailnet for CI, the local network for the nodes
  • Sequence diagram of the CI identity: the job asks GitHub for a token, Tailscale verifies it, the runner joins the tailnet and pushes to Harbor; the token's contents and the refused cases
    How CI joins the tailnet without a secret: a GitHub OIDC token verified by Tailscale
  • Backup diagram: the 10 pm CronJob, the Job's five steps, the NAS's NFS share, then the safe check and the restore
    The nightly backup of the srs database to the NAS, and the two ways to check or restore it
  • Monitoring diagram: Prometheus and its targets in the namespace, the two backup alert rules, the tailnet-only UI and what is planned for v2
    Monitoring: Prometheus scrapes the services, two rules watch the backup, the UI stays on the tailnet

Click an image to open it full screen and browse through the screenshots.

04 · Takeaways

What I took away from it

Describing infrastructure as code (Terraform): the machines are recreated identically, and Argo CD brings the cluster back to the state described in Git. A merge is enough to deploy.