README
¶
Schmetterpause
Matchmaking-, Liga- und Turnier-App für Büro-Tischtennis.
Go + templ + HTMX, Postgres, ein Container. Läuft in Docker Compose, Kubernetes und Azure Container Apps aus demselben Image.
Was man sieht
| Startseite | Turnier | Profil |
|---|---|---|
 |
 |
 |
- Startseite — was gerade läuft und dich betrifft, was auf deine Bestätigung wartet, und das Formular für ein Ergebnis. In dieser Reihenfolge.
- Turnier — Tabelle und Spielplan auf einer Seite, mit Tischseite und Eintragen-Knopf für die eigenen Paarungen.
- Profil — TTR, wie sie zustande kam, und die Matches dahinter.
Jede Seite einzeln, samt Kiosk, Aushang und Handy-Ansicht:
docs/bildschirme.md. Die Bilder stammen aus dem
Demo-Datenbestand, den task seed anlegt.
Status
Im Aufbau. Aktueller Meilenstein ist der MVP nach docs/mvp-plan.md: Ergebnisse
erfassen, vom Gegner bestätigen lassen, TTR berechnen, Rangliste anzeigen.
Liga-, Turnier- und Buchungsmodus kommen später.
Loslegen
Voraussetzungen: Task, Docker und die
Dagger-CLI. Beim ersten Aufruf einer
Dagger-Task einmalig task dagger:develop ausführen — das erzeugt die
generierten Teile des Pipeline-Moduls.
task up # Compose-Umgebung starten (App + Postgres)
task seed # Demo-Spieler und -Ergebnisse, damit die Seiten nicht leer sind
# (SP_SEED_FIXTURE=pong: die acht Bots und den Beobachter Pong)
task run # App lokal gegen die Compose-Datenbank, ohne Container
task ci # lint, test, build, verify — identisch zur Pipeline
task office:setup # .env für einen Abend an der Platte
task office:up # starten, im Netz erreichbar
Das Büro spielt seit dem 13.09.2026 auf der Instanz im Cluster — seit dem
28.09.2026 auf homerun2-dev2
(https://schmetterpause.homerun2-dev2.sthings-vsphere.labul.sva.de), davor auf
homerun2-test1 —, mit nächtlichem Backup. office:setup und office:up sind
der Weg für einen Abend mit eigenem Laptop — mit eigener Rangliste, siehe
Turnier vor Ort und
Spieldaten sichern und umziehen.
task up startet das veröffentlichte Image aus GHCR, nicht eines aus dem
Arbeitsverzeichnis — dasselbe Artefakt, das im Cluster läuft. Für den eigenen
Stand gibt es task run (schnell, ohne Container) und task up:local (baut das
Image mit Dagger und startet Compose damit).
Alle Befehle laufen über Task. Die eigentliche
Pipeline-Logik steckt in Dagger und läuft lokal wie in der
CI gleich — task ci ist kein Näherungswert, sondern derselbe Code.
task --list zeigt alle verfügbaren Tasks.
Dokumentation
Alles aus docs/ steht als Website unter
https://stuttgart-things.github.io/schmetterpause/ — mit Navigation und
Suche, und damit die bessere Adresse für alles, was jemand im Stehen oder auf
dem Handy liest. Diese Datei bleibt der Einstieg für alle, die das Repository
ohnehin ausgecheckt haben.
docs/bildschirme.md— jede Seite der App in einem Bild, am Demo-Datenbestand.CLAUDE.md— Invarianten, fachliche Begriffe, Konventionen. Vor Änderungen lesen.docs/mvp-plan.md— Scope, Datenmodell, Arbeitspakete, Definition of Done.docs/adr/— Architekturentscheidungen samt verworfener Alternativen. Der Index unterdocs/adr/index.mdwird generiert:task docs:index.docs/turnier-vor-ort.md— ein Abend an der Platte mit einem Laptop für alle.
Eine Änderung, die einem ADR widerspricht, braucht ein neues ADR mit
supersedes-Verweis.
Zum Namen
Schmetterball plus Pause. Der Name entstand aus einer Abstimmung im Büro und gilt als gesetzt — er steckt im Modulpfad, im Image-Namen und im Browser-Titel.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
schmetterpause
command
Command schmetterpause is the project's only binary.
|
Command schmetterpause is the project's only binary. |
|
Package db embeds the database migrations into the binary.
|
Package db embeds the database migrations into the binary. |
|
internal
|
|
|
auth
Package auth keeps authentication behind an interface.
|
Package auth keeps authentication behind an interface. |
|
checkin
Package checkin decides whether two check-ins prove a match (docs/adr/0024).
|
Package checkin decides whether two check-ins prove a match (docs/adr/0024). |
|
config
Package config reads the runtime configuration from the environment.
|
Package config reads the runtime configuration from the environment. |
|
credential
Package credential generates and checks the shared secrets a player proves themselves with: the recovery code from docs/adr/0006 and the PIN from docs/adr/0007.
|
Package credential generates and checks the shared secrets a player proves themselves with: the recovery code from docs/adr/0006 and the PIN from docs/adr/0007. |
|
domain
Package domain holds the application's business types.
|
Package domain holds the application's business types. |
|
match
Package match validates a proposed match result.
|
Package match validates a proposed match result. |
|
metrics
Package metrics is what the application measures about itself, for a scraper that reaches the pod directly (issue #175, level 2).
|
Package metrics is what the application measures about itself, for a scraper that reaches the pod directly (issue #175, level 2). |
|
qr
Package qr renders a QR code as SVG geometry.
|
Package qr renders a QR code as SVG geometry. |
|
ratelimit
Package ratelimit slows down guessing at a shared secret.
|
Package ratelimit slows down guessing at a shared secret. |
|
repository
Package repository defines data access as an interface.
|
Package repository defines data access as an interface. |
|
repository/postgres
Package postgres implements the repository interfaces on Postgres.
|
Package postgres implements the repository interfaces on Postgres. |
|
scoring
Package scoring settles a confirmed match.
|
Package scoring settles a confirmed match. |
|
seed
Package seed fills an empty database with a small, believable field.
|
Package seed fills an empty database with a small, believable field. |
|
server
Package server holds HTTP routing, middleware and handlers.
|
Package server holds HTTP routing, middleware and handlers. |
|
standings
Package standings turns player records into a ranking.
|
Package standings turns player records into a ranking. |
|
stats
Package stats answers questions about results that have already been agreed: who beat whom, and how much table tennis the office has actually played.
|
Package stats answers questions about results that have already been agreed: who beat whom, and how much table tennis the office has actually played. |
|
templates
templ: version: v0.3.1070
|
templ: version: v0.3.1070 |
|
tournament
Package tournament owns the two pieces of a round robin that are easy to get quietly wrong: who plays whom in which round, and where everybody stands once results arrive.
|
Package tournament owns the two pieces of a round robin that are easy to get quietly wrong: who plays whom in which round, and where everybody stands once results arrive. |
|
ttr
Package ttr implements the rating used by the German table tennis association (Tischtennis-Rating).
|
Package ttr implements the rating used by the German table tennis association (Tischtennis-Rating). |
|
zaehlwerk
Package zaehlwerk is the one call this application makes to the Zählwerk: claiming a table half for a player who checked in with their phone (docs/adr/0026).
|
Package zaehlwerk is the one call this application makes to the Zählwerk: claiming a table half for a player who checked in with their phone (docs/adr/0026). |
|
Package web embeds the static assets into the binary.
|
Package web embeds the static assets into the binary. |