PersonnelDifficile

Awlak Benjah

Suivi de diplôme et de moyenne hors ligne pour les étudiants de l'Université libanaise : une application Expo qui calcule sur le téléphone les moyennes pondérées par les crédits, la compensation et le verdict de réussite, avec une API NestJS pour les modèles, les sauvegardes et l'abonnement Shatour, et une console web pour l'administrer.

— Vue d'ensemble

Aperçu de l'architecture

apps/api · NestJS 12

packages

apps/mobile · Expo SDK 58

client typé

client typé

webhook

Écrans
contrôles natifs @expo/ui, Uniwind

Modules fonctionnels
diplômes, années, cours, notes, guide

expo-sqlite + Drizzle

Widget d'écran d'accueil

grading
règles de réussite

contracts
routes oRPC

schemas
Zod

Comptes
better-auth

Modèles, sauvegardes, droits d'accès

PostgreSQL

Redis

apps/web
console + démo étudiante

apps/showcase
Astro

RevenueCat

Cloudflare Workers

Awlak Benjah? (« est-ce que je vais réussir ? » en libanais) est un outil de suivi de diplôme et de moyenne pour les étudiants de l'Université libanaise. L'application modélise un diplôme en années, semestres, cours et notes sur 100, et calcule sur l'appareil les moyennes pondérées par les crédits, la compensation et le verdict de réussite ou d'échec de chaque année, sans aller-retour réseau et sans compte.

La difficulté, c'est que les règles de réussite ne tiennent pas en une formule. Une année peut être jugée semestre par semestre, où un cours est validé à 50 et une note de 40 à 49 est compensée quand le semestre atteint 55 de moyenne avec tous ses crédits, ou sur la moyenne de l'année pondérée par les crédits, et un même diplôme peut mêler les deux. Chaque règle est une stratégie dans un paquet de notation partagé, avec un juge, un plan qui alimente le guide de réussite, un verdict « inconnu » explicite, et un seul test d'invariants exécuté sur chaque règle, si bien que l'application, la démo web et les tests ne peuvent pas diverger.

Autour de ce cœur hors ligne vient un backend facultatif. Une API NestJS sert les modèles de diplôme, conserve les comptes et les sauvegardes, et décide de l'accès Premium (« Shatour » pour les étudiants) à partir d'un droit d'accès qu'écrit le webhook de RevenueCat. Chaque route est déclarée une seule fois comme contrat oRPC et consommée via un client typé par l'application comme par la console web, où se gèrent utilisateurs, abonnements et versions, à côté d'un chat IA qui lit les comptes et le journal d'audit via des outils MCP.

Dans l'application

L'application fonctionne d'abord en local : elle porte donc la logique métier qu'un backend porterait d'ordinaire. Son code est découpé en couches dont les imports ne vont que vers le bas, et ces règles sont vérifiées par dependency-cruiser à chaque contrôle, pas laissées à la relecture.

modules/ · 14 tranches verticales

implémente les ports

index.ts public uniquement

app/ + shell/
routes, layouts, providers

présentation
Views + ViewModels

application
cas d'usage, ports

domaine
sans framework

infrastructure
dépôts Drizzle

core/
base de données, i18n, requêtes, erreurs, logs

ui/
design system, compatible RTL

shared/
utilitaires feuilles

  • Quatorze modules, une carte des dépendances. Chaque module (diplômes, années, semestres, cours, notes, rapports, compte, sauvegarde et les autres) expose un index.ts pour les écrans et un model.ts pour son modèle sans framework, et ne peut importer que les modules listés pour lui. Un enfant connaît ses ancêtres, jamais l'inverse : ajouter une dépendance est une décision de relecture, pas une commodité.
  • Un MVVM qui a du mordant. Les Views affichent, les hooks ViewModel portent la logique. Un script fait échouer le contrôle à la moindre logique de calcul dans une View (.filter(, Math., un useState initialisé depuis une prop), et le lint interdit dans les fichiers de View les hooks qui portent de la logique, comme useEffect et useMemo.
  • Une unité de travail par cas d'usage. Un cas d'usage valide son entrée, s'exécute dans une seule transaction SQLite et renvoie des erreurs typées que les écrans traduisent en messages.
  • Le React Compiler est activé, donc ses règles de lint sont des erreurs : un composant qui en enfreint une perdrait son optimisation sans bruit.

setup / settings

rapports

sauvegarde

notes

compte

cours

semestres

années

diplômes

Une flèche désigne un module que l'autre peut importer (une partie de la carte des dépendances). Les modules de composition, comme les rapports, setup et settings, sont en amont, et aucun module fonctionnel ne les importe.

Un backend fondé sur les contrats

L'API, la console et l'application partagent une seule source de vérité pour chaque route.

comparé à main à chaque PR

packages/schemas
Zod, un sous-chemin par domaine

packages/contracts
routes oRPC + openapi.json

apps/api
implémente chaque route

packages/api-client
client typé

apps/mobile

console apps/web

contrôle des ruptures

  • NestJS 12 avec Drizzle sur PostgreSQL, des sessions lues dans Redis, better-auth pour les codes par e-mail, la connexion Apple et Google et la vérification en deux étapes des administrateurs, et chaque erreur renvoyée sous la forme { code, message }, pour que les clients traduisent le code au lieu d'afficher le message anglais.
  • Des routes versionnées sous /v1. Les applications installées continuent d'appeler ce avec quoi elles ont été publiées : un changement cassant est donc une nouvelle version, et la CI refuse celui qui n'est pas étiqueté comme tel.
  • La confidentialité est un contrat de publication. L'application n'envoie rien sur un étudiant tant qu'il ne crée pas de compte, et tout changement qui fait sortir des données de l'appareil met à jour la politique de confidentialité dans la même pull request.
  • La console (Vite, React, TanStack Router et Table) gère utilisateurs, abonnements, modèles, versions, logs, crashs et déploiements depuis un seul endroit, en rapatriant les données de Sentry et de RevenueCat plutôt que d'y renvoyer. Son chat IA lit via des outils MCP et rédige les notes de version et les textes des stores, et chaque écriture attend l'approbation d'un administrateur.

CI/CD

Chaque changement, aussi petit soit-il, suit le même chemin : une issue GitHub, une branche, une pull request fusionnée en squash, la préproduction, puis une version qui part en production. Rien n'est poussé directement sur main.

De l'issue à la production

Issue GitHub
sur le tableau du projet

Branche dans son
propre worktree

Contrôle local
pnpm check

Pull request
titre conventionnel

CI sur la PR

Fusion en squash

Déploiement en préproduction
applications concernées seulement

release-please
met à jour la PR de version

Version fusionnée
tag + release GitHub

Déploiement en production
API, puis web et vitrine

Build iOS sur EAS
vers TestFlight

La vie d'une pull request

release-pleasePréproductionCache TurborepoWorkflows CIGitHubIssue fermée, branche et worktree supprimésDéveloppeurpnpm check, tâches en cache rejouées1Ouvre la PR, liée à son issue2Lance la CI sur le commit de fusion3Détecte les paquets concernés4Rejoue les tâches inchangées5Contrôles par application, contrats, titre6Fusion en squash une fois au vert7Déploie les applications concernées8Le health check renvoie le commit fusionné9Met à jour la PR de version et le changelog10

Ce que lance la CI

api

api

contracts

mobile

web

showcase

pull_request

Changes
turbo ls --affected

Repo
Prettier, knip

Titre conventionnel

Contrôles API
lint, dépendances, types, tests

Image API
build + smoke test

Contrats
changements cassants

Contrôles mobile

Contrôles web + build

Contrôles vitrine + build

  • Seul ce qui a changé est contrôlé. Un job Changes demande à Turborepo quels paquets une pull request touche, y compris tout ce qui en dépend, et le job de chaque application ne s'exécute que si elle est concernée. Un paquet partagé fait donc recontrôler chaque application qui l'utilise.
  • Les contrôles d'une application sont les étapes d'un seul job (lint, règles de dépendances, typage, tests, build), car GitHub facture chaque job à la minute entamée. Ce choix a divisé la facture par deux par rapport à un job par contrôle. Chaque contrôle rend quand même son verdict si un précédent échoue, tandis que le build ne s'exécute que si tous les contrôles sont passés.
  • Un cache, deux endroits. Le cache distant de Turborepo est partagé par la CI et le contrôle local : une tâche dont les entrées sont déjà passées quelque part est rejouée en une seconde au lieu d'être relancée. Prettier garde aussi un cache par contenu.
  • La CI ne tourne que sur les pull requests. main n'avance que par des fusions en squash, et recontrôler chaque fusion coûtait plus de la moitié des minutes du plan gratuit.
  • Le contrôle des contrats régénère le document OpenAPI, le compare à celui de main et fait échouer une pull request qui casse /v1, sauf si elle est étiquetée comme une rupture voulue.
  • Un travail récent a fait passer une pull request API typique d'environ 8,5 à 4,5 minutes. L'image Docker se construit à côté des contrôles plutôt qu'après, et les 431 tests de l'API sont passés de 146 à 49 secondes en donnant à vitest un worker par cœur et en important l'application une fois par worker plutôt qu'une fois par fichier de test.

La mise en production

Web et vitrine

Déploiement de l'API

échec

Construire l'image
buildx + cache des couches

L'envoyer par SSH
vers une commande forcée

Lancer les migrations

Remplacer le conteneur

Health check

Retour à l'image précédente

wrangler deploy
vers Cloudflare Workers

  • La préproduction suit main : chaque fusion déploie les applications qu'elle touche, l'API d'abord, puisque le nouveau code web peut appeler de nouvelles routes.
  • La production est une version. release-please garde une pull request de version ouverte, avec la prochaine version et le changelog déduits des titres fusionnés. La fusionner crée le tag, déploie la production et construit l'application iOS sur EAS pour TestFlight quand l'application a changé.
  • L'API part en conteneur, sans registre : l'image est envoyée au serveur par SSH avec une clé qui ne peut lancer que le script de déploiement. Les migrations s'exécutent avant le remplacement, si bien qu'une migration ratée laisse l'ancien conteneur en service, et un health check en échec remet l'image précédente.
  • Autour de la chaîne : Renovate ne propose que les mises à jour cochées sur son tableau de bord, pnpm audit et expo-doctor tournent chaque semaine, et les deux bases de données sont sauvegardées chaque nuit vers Cloudflare R2.

Construit avec des agents IA

L'essentiel du code a été écrit avec Claude Code, selon les mêmes règles qu'un contributeur humain suivrait.

  • Chaque tâche est une issue GitHub, étiquetée et placée sur le tableau du projet, avec la consigne et les preuves de validation consignées en commentaires. Deux skills écrits pour ce dépôt, github-issues et ship-changes, portent le processus de l'issue à la production.
  • 28 skills d'agents vendorisés, épinglés par empreinte dans un fichier de verrouillage et relus comme du code : expo-ui d'Expo, les bonnes pratiques React Native et agent-device de Callstack pour piloter les simulateurs, les skills de contrats d'oRPC, Uniwind, les guides de sécurité de Better Auth, les skills d'animation et de design d'Emil Kowalski, et goldie pour les captures des stores. Les bibliothèques qui livrent leurs propres skills, comme drizzle-kit et TanStack Router, sont liées par pnpm à la version installée.
  • Des garde-fous plutôt que la confiance. Un AGENTS.md par application regroupe les conventions, un hook passe le lint sur chaque fichier qu'un agent modifie et lui renvoie les erreurs, et les règles d'architecture, le contrôle des Views et celui des contrats arrêtent un mauvais changement, quel qu'en soit l'auteur.
  • Des serveurs MCP pour la documentation de Better Auth, Sentry et drizzle-kit donnent aux agents le même contexte qu'un développeur irait chercher.

Fonctionnalités clés :

  • Modèle de données hors ligne sur expo-sqlite via Drizzle ORM, avec import d'un modèle en une seule transaction
  • Règles de réussite (credit-based, year-average) sous forme de stratégies dans @awlak-benjah/grading, partagées par l'application, la démo web et les tests
  • Un guide de réussite pour chaque cours ouvert, et avec Shatour la note dont chaque partie a besoin
  • Modèles de diplôme servis par l'API : les gratuits ouverts à tous, les payants verrouillés derrière l'écran d'abonnement
  • Un compte gratuit pour la sauvegarde et la restauration manuelles ; Shatour ajoute la sauvegarde automatique et le découpage des cours
  • Achats intégrés via RevenueCat, annuel et à vie, accordés comme droit d'accès sur le compte
  • Anglais, français et arabe, de droite à gauche en arabe, modes clair et sombre, et un widget d'écran d'accueil
  • Contrôles iOS natifs via @expo/ui, avec des mises en page React Native et une interface Liquid Glass
  • Une console web pour les utilisateurs, les abonnements et les modèles, où l'IA de la console rédige les textes des stores en trois langues

Stack technique :

  • Mobile : Expo SDK 58, React Native, Expo Router, @expo/ui, Uniwind, Reanimated, expo-widgets
  • Données : 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
  • Paiements et exploitation : RevenueCat, Sentry, Cloudflare Workers, Docker sur un VPS derrière Caddy, sauvegardes nocturnes de la base vers R2
  • Outillage : Turborepo, pnpm, TypeScript, oxlint, dependency-cruiser, Vitest, knip, release-please, Renovate

En chiffres (novembre 2026) : 603 commits depuis juillet 2026, 232 pull requests fusionnées, 13 versions, environ 1 300 tests (342 dans l'application, 178 dans le paquet de notation, 431 dans l'API, 197 dans la console et 159 dans la vitrine) et 17 workflows GitHub Actions.

Le dépôt est privé. L'application arrive sur iOS et Android, et sa vitrine se trouve sur awlak-benjah.com.

— Stack
TypeScriptReact NativeExpoAstroTailwind CSSTurborepoSQLiteDrizzle ORMCloudflareNestJSPostgreSQLReactViteZodiOSpnpmRevenueCatoRPCBetter AuthTanStackSentry