PersönlichSchwer

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.

— Überblick

Architekturüberblick

apps/api · NestJS 12

packages

apps/mobile · Expo SDK 58

typisierter Client

typisierter Client

Webhook

Bildschirme
native @expo/ui-Controls, Uniwind

Feature-Module
Studiengänge, Jahre, Kurse, Noten, Leitfaden

expo-sqlite + Drizzle

Homescreen-Widget

grading
Bestehensregeln

contracts
oRPC-Routen

schemas
Zod

Konten
better-auth

Vorlagen, Sicherungen, Berechtigungen

PostgreSQL

Redis

apps/web
Konsole + Demo für Studierende

apps/showcase
Astro

RevenueCat

Cloudflare Workers

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.

modules/ · 14 vertikale Schnitte

implementiert die Ports

nur über das öffentliche index.ts

app/ + shell/
Routen, Layouts, Provider

Präsentation
Views + ViewModels

Anwendung
Use Cases, Ports

Domäne
frameworkfrei

Infrastruktur
Drizzle-Repositories

core/
Datenbank, i18n, Queries, Fehler, Logging

ui/
Designsystem, RTL-fähig

shared/
Blatt-Helfer

  • Vierzehn Module, eine Abhängigkeitskarte. Jedes Modul (Studiengänge, Jahre, Semester, Kurse, Noten, Berichte, Konto, Sicherung und die übrigen) stellt ein index.ts für die Bildschirme und ein model.ts fü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., ein useState, das aus einer Prop initialisiert wird), und der Lint verbietet in View-Dateien die Hooks, die Logik tragen, etwa useEffect und useMemo.
  • 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.

setup / settings

Berichte

Sicherung

Noten

Konto

Kurse

Semester

Jahre

Studiengänge

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.

bei jedem PR mit main verglichen

packages/schemas
Zod, ein Unterpfad pro Domäne

packages/contracts
oRPC-Routen + openapi.json

apps/api
implementiert jede Route

packages/api-client
typisierter Client

apps/mobile

Konsole apps/web

Prüfung auf Breaking Changes

  • 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

GitHub-Issue
auf dem Projekt-Board

Branch in eigenem
Worktree

Lokale Prüfung
pnpm check

Pull Request
konventioneller Titel

CI auf dem PR

Squash-Merge

Staging-Deployment
nur betroffene Apps

release-please
aktualisiert den Release-PR

Release gemergt
Tag + GitHub-Release

Produktions-Deployment
API, dann Web und Showcase

iOS-Build auf EAS
für TestFlight

Der Lebenslauf eines Pull Requests

release-pleaseStagingTurborepo-CacheCI-WorkflowsGitHubIssue geschlossen, Branch und Worktree gelöschtEntwicklerpnpm check, gecachte Tasks werden abgespielt1PR öffnen, mit seinem Issue verknüpft2CI auf dem Merge-Commit starten3Betroffene Pakete ermitteln4Unveränderte Tasks abspielen5Prüfungen pro App, Verträge, Titel6Squash-Merge, sobald alles grün ist7Betroffene Apps ausrollen8Health-Check meldet den gemergten Commit9Release-PR und Changelog aktualisieren10

Was die CI ausführt

api

api

contracts

mobile

web

showcase

pull_request

Changes
turbo ls --affected

Repo
Prettier, knip

Konventioneller Titel

API-Prüfungen
Lint, Abhängigkeiten, Typen, Tests

API-Image
Build + Smoke-Test

Verträge
Breaking Changes

Mobile-Prüfungen

Web-Prüfungen + Build

Showcase-Prüfungen + Build

  • 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. main bewegt 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 main und lässt einen Pull Request scheitern, der /v1 bricht, 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

Web und Showcase

API-Deployment

scheitert

Image bauen
buildx + Layer-Cache

Per SSH an einen
erzwungenen Befehl streamen

Migrationen ausführen

Container austauschen

Health-Check

Vorheriges Image zurück

wrangler deploy
zu Cloudflare Workers

  • 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 audit und expo-doctor laufen 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-issues und ship-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-ui von Expo, die React-Native-Best-Practices und agent-device von 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 und goldie fü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.md pro 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.

— Stack
TypeScriptReact NativeExpoAstroTailwind CSSTurborepoSQLiteDrizzle ORMCloudflareNestJSPostgreSQLReactViteZodiOSpnpmRevenueCatoRPCBetter AuthTanStackSentry