PersonalHard

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.

— Overview

Architecture Overview

apps/api · NestJS 12

packages

apps/mobile · Expo SDK 58

typed client

typed client

webhook

Screens
@expo/ui native controls, Uniwind

Feature modules
degrees, years, courses, grades, guide

expo-sqlite + Drizzle

Home screen widget

grading
passing behaviors

contracts
oRPC routes

schemas
Zod

Accounts
better-auth

Presets, backups, entitlements

PostgreSQL

Redis

apps/web
console + student demo

apps/showcase
Astro

RevenueCat

Cloudflare Workers

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.

modules/ · 14 vertical slices

implements ports

public index.ts only

app/ + shell/
routes, layouts, providers

presentation
Views + ViewModels

application
use cases, ports

domain
framework-free

infrastructure
Drizzle repositories

core/
database, i18n, query, errors, logger

ui/
design system, RTL-aware

shared/
leaf helpers

  • Fourteen modules, one edge map. Each module (degrees, years, semesters, courses, grades, reports, account, backup and the rest) exposes an index.ts for screens and a model.ts for 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., a useState seeded from a prop), and lint bans the hooks that hold logic, such as useEffect and useMemo, 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.

setup / settings

reports

backup

grades

account

courses

semesters

years

degrees

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.

compared with main on every PR

packages/schemas
Zod, one subpath per domain

packages/contracts
oRPC routes + openapi.json

apps/api
implements each route

packages/api-client
typed client

apps/mobile

apps/web console

breaking-change check

  • 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

GitHub issue
on the project board

Branch in its
own worktree

Local gate
pnpm check

Pull request
conventional title

CI on the PR

Squash merge

Staging deploy
affected apps only

release-please
updates the release PR

Release merged
tag + GitHub release

Production deploy
API, then web and showcase

iOS build on EAS
to TestFlight

The life of a pull request

release-pleaseStagingTurborepo cacheCI workflowsGitHubIssue closed, branch and worktree deletedDeveloperpnpm check, cached tasks replayed1Open the PR, linked to its issue2Run CI on the merge commit3Detect affected packages4Replay unchanged tasks5Checks per app, contract check, title check6Squash merge once green7Deploy the affected apps8Health check reports the merged commit9Update the release PR and changelog10

What CI runs

api

api

contracts

mobile

web

showcase

pull_request

Changes
turbo ls --affected

Repo
Prettier, knip

Conventional title

API checks
lint, deps, types, tests

API image
build + smoke test

Contract
breaking changes

Mobile checks

Web checks + build

Showcase checks + build

  • Only what changed runs. A Changes job 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. main moves 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 /v1 unless 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

Web and showcase

API deploy

fails

Build the image
buildx + layer cache

Stream it over SSH
to a forced command

Run migrations

Swap the container

Health check

Previous image back

wrangler deploy
to Cloudflare Workers

  • 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 audit and expo-doctor run 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-issues and ship-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 and agent-device for driving simulators, oRPC's contract skills, Uniwind, Better Auth's security guides, Emil Kowalski's animation and design skills, and goldie for 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.md per 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-sqlite through 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.

— Stack
TypeScriptReact NativeExpoAstroTailwind CSSTurborepoSQLiteDrizzle ORMCloudflareNestJSPostgreSQLReactViteZodiOSpnpmRevenueCatoRPCBetter AuthTanStackSentry