Awlak Benjah
Offline-first-Tracker für Studiengang und Notendurchschnitt für Studierende der Libanesischen Universität: eine Expo-App, die nach Credits gewichtete Durchschnitte, Kompensation und das Bestehensurteil auf dem Handy berechnet, mit einer NestJS-API für Vorlagen, Sicherungen und das Shatour-Abo und einer Web-Konsole für den Betrieb.




Architekturüberblick
Awlak Benjah? (Libanesisch für „Werde ich bestehen?“) ist ein Tracker für Studiengang und Notendurchschnitt für Studierende der Libanesischen Universität. Die App bildet einen Studiengang als Jahre, Semester, Kurse und Noten bis 100 ab und berechnet nach Credits gewichtete Durchschnitte, Kompensation und das Urteil „bestanden“ oder „nicht bestanden“ für jedes Jahr direkt auf dem Gerät, ohne Netzwerk-Roundtrip und ohne Konto.
Schwierig ist, dass die Bestehensregeln keine einzelne Formel sind. Ein Jahr kann Semester für Semester bewertet werden, wobei ein Kurs ab 50 besteht und 40 bis 49 kompensiert wird, wenn das Semester mit vollen Credits einen Durchschnitt von 55 erreicht, oder über den nach Credits gewichteten Jahresdurchschnitt, und ein Studiengang kann beides mischen. Jede Regel ist eine Strategie in einem gemeinsamen Grading-Paket, mit einem Judge, einem Plan, der den Bestehensleitfaden speist, einem expliziten Urteil „unbekannt“ und einem einzigen Invariantentest über alle Regeln, sodass App, Web-Demo und Tests nicht auseinanderlaufen können.
Um den Offline-Kern liegt ein optionales Backend. Eine NestJS-API liefert die Studiengangsvorlagen, verwaltet Konten und Sicherungen und entscheidet über Premium („Shatour“ bei den Studierenden) anhand einer Berechtigung, die der Webhook von RevenueCat schreibt. Jede Route ist einmal als oRPC-Vertrag deklariert und wird über einen typisierten Client von der App wie von der Web-Konsole genutzt, in der Nutzer, Abos und Releases verwaltet werden, neben einem KI-Chat, der Konten und das Audit-Log über MCP-Tools liest.
Im Inneren der App
Die App arbeitet lokal zuerst und trägt deshalb die Domänenlogik, die sonst ein Backend übernähme. Ihr Code ist in Schichten geteilt, deren Importe nur nach unten zeigen, und dependency-cruiser setzt diese Regeln bei jeder Prüfung durch, statt sie dem Review zu überlassen.
- Vierzehn Module, eine Abhängigkeitskarte. Jedes Modul (Studiengänge, Jahre, Semester,
Kurse, Noten, Berichte, Konto, Sicherung und die übrigen) stellt ein
index.tsfür die Bildschirme und einmodel.tsfür sein frameworkfreies Modell bereit und darf nur die für es gelisteten Module importieren. Ein Kind kennt seine Vorfahren, nie umgekehrt, also ist eine neue Abhängigkeit eine Review-Entscheidung, keine Bequemlichkeit. - MVVM mit Biss. Views rendern, ViewModel-Hooks halten die Logik. Ein Skript lässt die
Prüfung bei jeder Berechnung in einer View scheitern (
.filter(,Math., einuseState, das aus einer Prop initialisiert wird), und der Lint verbietet in View-Dateien die Hooks, die Logik tragen, etwauseEffectunduseMemo. - Eine Unit of Work pro Use Case. Ein Use Case prüft seine Eingabe, läuft in einer einzigen SQLite-Transaktion und gibt typisierte Fehler zurück, die die Bildschirme in übersetzte Meldungen verwandeln.
- Der React Compiler ist aktiv, deshalb sind seine Lint-Regeln Fehler: Eine Komponente, die eine davon verletzt, verlöre still ihre Optimierung.
Ein Pfeil zeigt auf ein Modul, das das andere importieren darf (ein Ausschnitt der Abhängigkeitskarte). Die Kompositionsmodule wie Berichte, setup und settings stehen oben, und kein Feature-Modul importiert sie.
Ein vertragsbasiertes Backend
API, Konsole und App teilen sich für jede Route eine einzige Quelle der Wahrheit.
- NestJS 12 mit Drizzle auf PostgreSQL, Sitzungen aus Redis, better-auth für E-Mail-Codes,
Anmeldung mit Apple und Google und Zwei-Schritt-Verifizierung für Admins, und jeder Fehler
kommt als
{ code, message }zurück, damit die Clients den Code übersetzen, statt die englische Meldung zu zeigen. - Versionierte Routen unter
/v1. Installierte Apps rufen weiter auf, womit sie ausgeliefert wurden, deshalb ist eine inkompatible Änderung eine neue Version, und die CI lehnt eine ab, die nicht als solche gekennzeichnet ist. - Datenschutz ist ein Release-Vertrag. Die App sendet nichts über Studierende, solange sie kein Konto anlegen, und jede Änderung, die Daten vom Gerät schickt, aktualisiert die Datenschutzerklärung im selben Pull Request.
- Die Konsole (Vite, React, TanStack Router und Table) verwaltet Nutzer, Abos, Vorlagen, Releases, Logs, Abstürze und Deployments an einem Ort und holt die Daten von Sentry und RevenueCat herein, statt dorthin zu verlinken. Ihr KI-Chat liest über MCP-Tools und entwirft Release Notes und Store-Texte, und jede Schreibaktion wartet auf die Freigabe eines Admins.
CI/CD
Jede Änderung, egal wie klein, nimmt denselben Weg: ein GitHub-Issue, ein Branch, ein per
Squash gemergter Pull Request, Staging und schließlich ein Release, das die Produktion
ausliefert. Nichts wird direkt auf main gepusht.
Vom Issue bis zur Produktion
Der Lebenslauf eines Pull Requests
Was die CI ausführt
- Geprüft wird nur, was sich geändert hat. Ein
Changes-Job fragt Turborepo, welche Pakete ein Pull Request berührt, samt allem, was davon abhängt, und der Job jeder App läuft nur, wenn sie betroffen ist. Ein gemeinsames Paket prüft daher jede App erneut, die es nutzt. - Die Prüfungen einer App sind Schritte eines einzigen Jobs (Lint, Abhängigkeitsregeln, Typprüfung, Tests, Build), weil GitHub jeden Job pro angefangener Minute abrechnet. Das hat die Rechnung gegenüber einem Job pro Prüfung halbiert. Jede Prüfung meldet trotzdem ihr Ergebnis, auch wenn eine frühere scheitert, während der Build nur läuft, wenn alle Prüfungen bestanden sind.
- Ein Cache, zwei Orte. Der Remote-Cache von Turborepo wird von CI und lokaler Prüfung geteilt, also wird ein Task, dessen Eingaben irgendwo schon bestanden haben, in einer Sekunde abgespielt, statt neu zu laufen. Auch Prettier hält einen inhaltsbasierten Cache.
- Die CI läuft nur auf Pull Requests.
mainbewegt sich nur durch Squash-Merges, und jeden Merge erneut zu prüfen, kostete mehr als die Hälfte der Minuten des Gratisplans. - Die Vertragsprüfung erzeugt das OpenAPI-Dokument neu, vergleicht es mit dem von
mainund lässt einen Pull Request scheitern, der/v1bricht, außer er ist als gewollter Bruch gekennzeichnet. - Jüngste Arbeit hat einen typischen API-Pull-Request von etwa 8,5 auf 4,5 Minuten gebracht. Das Docker-Image wird neben den Prüfungen gebaut statt danach, und die 431 API-Tests liefen statt 146 nur noch 49 Sekunden, weil vitest einen Worker pro Kern bekam und die App einmal pro Worker statt einmal pro Testdatei importiert wird.
Auslieferung
- Staging folgt
main: Jeder Merge rollt die Apps aus, die er betrifft, die API zuerst, da neuer Web-Code neue Routen aufrufen kann. - Produktion ist ein Release. release-please hält einen Release-Pull-Request offen, mit der nächsten Version und dem Changelog aus den gemergten Titeln. Ihn zu mergen setzt den Tag, rollt die Produktion aus und baut die iOS-App auf EAS für TestFlight, wenn sich die App geändert hat.
- Die API wird als Container ausgeliefert, ohne Registry: Das Image wird per SSH mit einem Schlüssel auf den Server gestreamt, der nur das Deploy-Skript ausführen kann. Migrationen laufen vor dem Austausch, sodass eine gescheiterte Migration den alten Container weiterlaufen lässt, und ein gescheiterter Health-Check holt das vorherige Image zurück.
- Rund um die Pipeline: Renovate schlägt nur die Updates vor, die auf seinem Dashboard
angehakt sind,
pnpm auditundexpo-doctorlaufen wöchentlich, und beide Datenbanken werden jede Nacht nach Cloudflare R2 gesichert.
Mit KI-Agenten gebaut
Der Großteil des Codes entstand mit Claude Code, nach denselben Regeln, denen auch ein menschlicher Mitwirkender folgen würde.
- Jede Aufgabe ist ein GitHub-Issue, gelabelt und auf dem Projekt-Board, mit Auftrag und
Abnahmenachweisen als Kommentaren. Zwei für dieses Repository geschriebene Skills,
github-issuesundship-changes, tragen den Ablauf vom Issue bis zur Produktion. - 28 eingebundene Agent-Skills, per Hash in einer Lock-Datei fixiert und wie Code reviewt:
expo-uivon Expo, die React-Native-Best-Practices undagent-devicevon Callstack zum Steuern von Simulatoren, die Vertrags-Skills von oRPC, Uniwind, die Sicherheitsleitfäden von Better Auth, die Animations- und Design-Skills von Emil Kowalski undgoldiefür die Store-Screenshots. Bibliotheken, die eigene Skills mitliefern, etwa drizzle-kit und TanStack Router, verlinkt pnpm in der installierten Version. - Leitplanken statt Vertrauen. Ein
AGENTS.mdpro App hält die Konventionen fest, ein Hook lintet jede Datei, die ein Agent bearbeitet, und gibt ihm die Fehler zurück, und die Architekturregeln, die View-Prüfung und die Vertragsprüfung stoppen eine falsche Änderung, egal wer sie geschrieben hat. - MCP-Server für die Dokumentation von Better Auth, für Sentry und für drizzle-kit geben den Agenten denselben Kontext, den ein Entwickler nachschlagen würde.
Hauptfunktionen:
- Offline-Datenmodell auf
expo-sqliteüber Drizzle ORM, eine Vorlage wird in einer einzigen Transaktion importiert - Bestehensregeln (
credit-based,year-average) als Strategien in@awlak-benjah/grading, gemeinsam genutzt von App, Web-Demo und Tests - Ein Bestehensleitfaden für jeden offenen Kurs, mit Shatour auch die Punktzahl, die jeder Notenteil braucht
- Studiengangsvorlagen von der API: kostenlose für alle, kostenpflichtige hinter der Bezahlseite
- Ein kostenloses Konto für manuelles Sichern und Wiederherstellen; Shatour ergänzt automatische Sicherung und aufgeteilte Kurse
- In-App-Käufe über RevenueCat, jährlich und lebenslang, als Berechtigung am Konto vergeben
- Englisch, Französisch und Arabisch, auf Arabisch von rechts nach links, heller und dunkler Modus und ein Homescreen-Widget
- Native iOS-Controls über
@expo/ui, mit React-Native-Layouts und Liquid-Glass-Chrome - Eine Web-Konsole für Nutzer, Abos und Vorlagen, in der das KI-Modell der Konsole Store-Texte in drei Sprachen entwirft
Tech-Stack:
- Mobile: Expo SDK 58, React Native, Expo Router, @expo/ui, Uniwind, Reanimated, expo-widgets
- Daten: expo-sqlite, Drizzle ORM, Zustand, TanStack Query, Zod
- API: NestJS 12, oRPC, better-auth, PostgreSQL, Redis, Resend, Vercel AI SDK
- Web: Vite, React, TanStack Router, TanStack Table
- Zahlungen und Betrieb: RevenueCat, Sentry, Cloudflare Workers, Docker auf einem VPS hinter Caddy, nächtliche Datenbank-Backups nach R2
- Tooling: Turborepo, pnpm, TypeScript, oxlint, dependency-cruiser, Vitest, knip, release-please, Renovate
In Zahlen (November 2026): 603 Commits seit Juli 2026, 232 gemergte Pull Requests, 13 Releases, rund 1.300 Tests (342 in der App, 178 im Grading-Paket, 431 in der API, 197 in der Konsole und 159 im Showcase) und 17 GitHub-Actions-Workflows.
Das Repository ist privat. Die App kommt für iOS und Android, ihre Showcase-Seite liegt unter awlak-benjah.com.