Digital authorization platform for flexible, verifiable student pickup in Kenyan boarding schools. Replaces handwritten letters and unverifiable phone calls with time-bound QR/OTP tokens, a pre-approved "Pickup Circle," USSD/SMS fallback for feature-phone users, and a full audit trail for administrators.
Boarding schools only release students to pre-listed guardians, but real life doesn't cooperate — sick parents, diaspora work, emergencies, trusted relatives stepping in. Today that's handled with forged-prone paper letters, teachers' personal WhatsApp, and unverifiable phone calls. No audit trail exists. Post-Endarasha, the Ministry of Education is pushing schools toward exactly this kind of accountability.
| Actor | Interface |
|---|---|
| Parent / Guardian | Mobile app (+ USSD/SMS fallback) |
| Authorized Picker | Mobile app / SMS OTP |
| Class Teacher / Gate Security | Tablet "scan & verify" app |
| School Administrator | Web dashboard |
| Ministry of Education (future) | Export/reporting API |
┌──────────────────────────── TIER 1: CLIENTS ────────────────────────────┐
│ Parent/Picker Teacher/Gate Admin Web USSD/SMS │
│ Mobile App Tablet App Dashboard (feature phones) │
│ (React Native) (React Native) (React SPA) via gateway │
└──────────────┬───────────────┬───────────────┬───────────────┬──────────┘
HTTPS/TLS 1.3 (all client traffic, no exceptions)
┌──────────────▼───────────────▼───────────────▼───────────────▼─────────┐
│ TIER 2: APPLICATION SERVER │
│ API Gateway → Auth Rate-Limit WAF │
│ ├─ Auth Service (OTP issuance, JWT, session mgmt, RBAC) │
│ ├─ Pickup Circle Service (guardian registration, ID verification) │
│ ├─ Authorization Service (pickup requests, time-window validation) │
│ ├─ Token Service (QR + OTP generation, single-use, signed) │
│ ├─ Gate Verification Svc (offline-capable token validation) │
│ ├─ Notification Service (SMS/USSD gateway, push notifications) │
│ ├─ Emergency Override Svc (admin-issued, fully logged) │
│ └─ Audit/Reporting Service (tamper-evident event log, PDF/CSV export) │
└──────────────────────────────────┬─────────────────────────────────────┘
encrypted connection, least-privilege DB user
┌──────────────────────────────────▼──────────────────────────────────────┐
│ TIER 3: DATA LAYER │
│ Primary DB (Postgres) D1 Users · D2 Auth Records · D3 Tokens │
│ Audit Store (append-only) D4 Gate Verification Log │
│ Object Storage (encrypted) ID photos, signed letters │
│ Cache (Redis) active token lookups for offline sync │
└─────────────────────────────────────────────────────────────────────────┘
Strict tier separation: clients never touch the database directly; every write goes through the application server's service layer, which is the only tier holding DB credentials.
This system touches child safety, national ID numbers, and location/timing of minors — treat it like a security-critical system, not a CRUD app.
- Identity verification: National ID + selfie match at Pickup Circle enrollment; admin approval required before a picker is "live."
- Tokens are single-use, short-lived, and cryptographically signed (JWT/HMAC) — not guessable, not reusable after redemption.
- Zero plaintext secrets: OTPs delivered via SMS only, never logged in plaintext server-side; hashed at rest if persisted at all.
- Transport security: TLS everywhere; certificate pinning on mobile clients.
- RBAC, enforced server-side per role (parent / picker / teacher / admin) — never trust a client-side role flag.
- Rate limiting & abuse protection on OTP requests, gate verification attempts, and USSD sessions (closing-day concurrency is a known load spike and a known attack window).
- Tamper-evident audit log: append-only, every pickup event and every emergency override immutably timestamped with the acting admin's identity — this is the system's core value proposition, not an afterthought.
- PII minimization & encryption at rest: National ID numbers and ID photos encrypted at rest (KMS-managed keys), access scoped and logged.
- Emergency override accountability: every override requires a logged reason, is time-boxed (30 min), and notifies the parent in parallel — no silent overrides.
- Offline gate verification: gate app must validate previously-synced tokens without live connectivity, without weakening signature checks (pre-fetch signed token batches, verify signature locally).
- Secrets management: no secrets in source control — env vars / secrets manager only.
- Regular dependency and OWASP Top 10 review, especially injection and broken-auth classes given the multiple entry points (app, web, USSD, SMS).
| Layer | Choice | Why |
|---|---|---|
| Mobile (parent/picker/teacher) | React Native | Single codebase, offline-first support |
| Admin web | React + TypeScript | Dashboard, reporting, export |
| API server | Node.js (NestJS) or Python (FastAPI) | Strong auth/middleware ecosystem |
| Database | PostgreSQL | Relational integrity for auth chains |
| Cache/session | Redis | Token lookups, rate limiting |
| SMS/USSD gateway | Africa's Talking or Twilio | Kenya-native SMS/USSD support |
| Push notifications | Firebase Cloud Messaging | Cross-platform |
| Auth | JWT + short-lived refresh tokens | Stateless, revocable |
| Infra | Docker + CI/CD (GitHub Actions) | Reproducible deploys |
- Auth & Pickup Circle — registration, OTP login, National ID verification, admin approval queue.
- Authorization + Token Service — pickup request → QR/OTP generation → delivery.
- Gate Verification app — scan/enter, AUTHORIZED/DECLINED screen, offline validation, release logging.
- Notification layer — parent push/SMS confirmation on collection.
- Emergency Override — admin flow with mandatory reason + time-box.
- USSD/SMS fallback — feature-phone authorization path.
- Audit & Reporting dashboard — filterable logs, PDF/CSV export.
- Security hardening pass — pen-test, rate-limit tuning, load test for closing-day concurrency.
- Pilot — 2–3 schools, one term, real closing-day event.
Modern, high-contrast, mobile-first. Large touch targets and minimal text for the gate app (elderly/low-literacy users must be able to interpret AUTHORIZED/DECLINED at a glance — green/red is load-bearing, not decorative). Swahili + English throughout. Parent app should echo the M-Pesa OTP mental model users already trust.
safepass/
├── apps/
│ ├── mobile-parent-picker/
│ ├── mobile-gate/
│ └── admin-dashboard/
├── services/
│ ├── auth-service/
│ ├── pickup-circle-service/
│ ├── authorization-service/
│ ├── token-service/
│ ├── gate-verification-service/
│ ├── notification-service/
│ └── audit-service/
├── infra/
│ ├── docker/
│ └── ci/
├── docs/
│ └── SafePass_INTE451_Report.docx
└── README.md