Awlak Benjah
Offline-first degree and GPA tracker for Lebanese University students: an Expo app that works out credit-weighted averages, compensation and the pass verdict on the phone, with a NestJS API for presets, backups and the Shatour subscription, and a web console to run it.




Architecture Overview
Awlak Benjah? ("will I pass?" in Lebanese) is a degree and GPA tracker for Lebanese University students. The app models a degree as years, semesters, courses and grades out of 100, and works out credit-weighted averages, compensation and each year's pass or fail verdict on the device, with no network round trip and no account.
The hard part is that the passing rules are not one formula. A year can be judged semester by semester, where a course passes at 50 and 40 to 49 is compensated when the semester averages 55 with its full credits, or on the year's credit-weighted average, and one degree can mix both. Each rule is a strategy in a shared grading package, with a judge, a plan that drives the passing guide, an explicit "unknown" verdict, and one invariant test run over every behavior, so the app, the web demo and the tests cannot disagree.
Around the offline core sits an optional backend. A NestJS API serves the degree presets, keeps accounts and backups, and decides Premium ("Shatour" to students) from an entitlement that RevenueCat's webhook writes. Every route is declared once as an oRPC contract and consumed through a typed client by both the app and the web console, where users, subscriptions and releases are managed, beside an AI chat that reads accounts and the audit log through MCP tools.
Inside the app
The app is local-first, so it carries the domain logic a backend would otherwise hold. Its code is split into layers whose imports only point downward, and the rules are enforced by dependency-cruiser on every check, not left to review.
- Fourteen modules, one edge map. Each module (degrees, years, semesters,
courses, grades, reports, account, backup and the rest) exposes an
index.tsfor screens and amodel.tsfor its framework-free model, and may import only the modules listed for it. A child knows its ancestors, never the reverse, so adding an edge is a review decision rather than a convenience. - MVVM with teeth. Views render; ViewModel hooks hold the logic. A script
fails the check on any computation inside a View (
.filter(,Math., auseStateseeded from a prop), and lint bans the hooks that hold logic, such asuseEffectanduseMemo, from View files. - One unit of work per use case. A use case validates its input, runs in a single SQLite transaction and returns typed errors that the screens turn into translated messages.
- The React Compiler is on, so its lint rules are errors: a component that breaks one would silently lose its optimisation.
An arrow points at a module the other may import (part of the edge map). The composition modules, such as reports, setup and settings, sit upstream, and no feature module imports them.
Contract-first backend
The API, the console and the app share one source of truth for every route.
- NestJS 12 with Drizzle over PostgreSQL, sessions read from Redis,
better-auth for email codes, Apple and Google sign-in and two-step
verification for admins, and every error answered as
{ code, message }so the clients translate the code rather than show the English message. - Versioned routes under
/v1. Installed apps keep calling what they shipped with, so a breaking change is a new version, and CI refuses one that isn't labelled as such. - Privacy is a release contract. The app sends nothing about a student unless they create an account, and any change that sends data off the device updates the privacy policy in the same pull request.
- The console (Vite, React, TanStack Router and Table) runs users, subscriptions, presets, releases, logs, crashes and deploys from one place, bringing Sentry and RevenueCat data in instead of linking out. Its AI chat reads through MCP tools and drafts release notes and store text, and every write waits for an admin's approval.
CI/CD
Every change, however small, travels the same road: a GitHub issue, a branch,
a squash-merged pull request, staging, then a release that ships production.
Nothing is pushed to main directly.
From issue to production
The life of a pull request
What CI runs
- Only what changed runs. A
Changesjob asks Turborepo which packages a pull request affects, including everything that depends on them, and each app's job runs only when its app is affected. A shared package therefore re-checks every app that uses it. - Each app's checks are steps of one job (lint, dependency rules, typecheck, tests, build), because GitHub bills every job by the started minute. That choice halved the bill against a job per check. Each check still reports even when an earlier one fails, while the build runs only when every check passed.
- One cache, two places. Turborepo's remote cache is shared by CI and the local gate, so a task whose inputs already passed anywhere is replayed in a second rather than run again. Prettier keeps a content cache too.
- CI runs on pull requests only.
mainmoves only through squash merges, and re-checking every merge cost more than half of the free plan's minutes. - The contract check regenerates the OpenAPI document, compares it with
main's, and fails a pull request that breaks/v1unless it is labelled as a deliberate break. - Recent work cut a typical API pull request from about 8.5 to 4.5 minutes. The Docker image builds beside the checks instead of after them, and the API's 431 tests went from 146 to 49 seconds by giving vitest a worker per core and importing the app once per worker instead of once per test file.
Shipping
- Staging follows
main: every merge deploys the apps it affected, the API first, since new web code may call new routes. - Production is a release. release-please keeps one release pull request open, with the next version and changelog read from the merged titles. Merging it tags the release, deploys production, and builds the iOS app on EAS for TestFlight when the app changed.
- The API ships as a container with no registry: the image is streamed to the server over SSH with a key that can run only the deploy script. Migrations run before the swap, so a failed one leaves the old container serving, and a failed health check puts the previous image back.
- Around the pipeline: Renovate proposes only the updates ticked on its
dashboard,
pnpm auditandexpo-doctorrun weekly, and both databases are dumped nightly to Cloudflare R2.
Built with AI agents
Most of the code was written with Claude Code, working from the same rules a human contributor would follow.
- Every task is a GitHub issue, labelled and on the project board, with
the brief and the acceptance evidence recorded as comments. Two skills
written for this repository,
github-issuesandship-changes, carry the process from issue to production. - 28 vendored agent skills, pinned by hash in a lockfile and reviewed like
code: Expo's
expo-ui, Callstack's React Native best practices andagent-devicefor driving simulators, oRPC's contract skills, Uniwind, Better Auth's security guides, Emil Kowalski's animation and design skills, andgoldiefor the store screenshots. Libraries that ship their own skills, such as drizzle-kit and TanStack Router, are linked by pnpm at the installed version. - Guardrails over trust. An
AGENTS.mdper app holds the conventions, a hook lints every file an agent edits and hands the errors back, and the architecture rules, the View check and the contract check stop a wrong change whoever wrote it. - MCP servers for Better Auth's documentation, Sentry and drizzle-kit give the agents the same context a developer looks up.
Key Features:
- Offline data model on
expo-sqlitethrough Drizzle ORM, with a preset imported in one transaction - Passing behaviors (
credit-based,year-average) as strategies in@awlak-benjah/grading, shared by the app, the web demo and the tests - A passing guide for every open course, and with Shatour the score each grade part needs
- Degree presets served by the API: free ones open to everyone, paid ones locked behind the paywall
- A free account for manual backup and restore; Shatour adds automatic backup and course breakdowns
- In-app purchases through RevenueCat, yearly and lifetime, granted as an account entitlement
- English, French and Arabic, right to left in Arabic, light and dark mode, and a home screen widget
- Native iOS controls through
@expo/ui, with React Native layouts and Liquid Glass chrome - A web console for users, subscriptions and presets, with store notes drafted in three languages by the console's model
Tech Stack:
- Mobile: Expo SDK 58, React Native, Expo Router, @expo/ui, Uniwind, Reanimated, expo-widgets
- Data: 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
- Payments and ops: RevenueCat, Sentry, Cloudflare Workers, Docker on a VPS behind Caddy, nightly database backups to R2
- Tooling: Turborepo, pnpm, TypeScript, oxlint, dependency-cruiser, Vitest, knip, release-please, Renovate
By the numbers (November 2026): 603 commits since July 2026, 232 merged pull requests, 13 releases, about 1,300 tests (342 in the app, 178 in the grading package, 431 in the API, 197 in the console and 159 in the showcase) and 17 GitHub Actions workflows.
The repository is private. The app is coming to iOS and Android, and its showcase is at awlak-benjah.com.