Documentation
Architecture, data, and what’s built
1. What this prototype implements
| Module | Scope | Status |
|---|---|---|
| Student journey | 6-step wizard, autosave, back without loss, drag-and-drop ranking, admin-set limits | Working |
| Matching engine | Transparent rules: unified grade, language, curriculum, budget, deadline, discounts; no filler | Working |
| Shortlist & payment | 5/country, 25 total; test payment with success/failure; receipts; idempotency keys | Simulated |
| Applications & offers | Full status lifecycle, expiring offers, acceptance, enrollment invoice with one-time deposit credit | Simulated |
| University portal | Domain email + code + manual review; programs & fees; applications; group offers; ambassadors; team; reports | Working |
| Super Admin | KPIs, verification & publishing, fees/limits/commission/FX, taxonomy, geography, refunds, audit log | Working |
| Bilingual | Every screen and message in Arabic (RTL) and English (LTR) | Working |
This prototype runs entirely in the browser, with data saved locally in your browser only. It sends no real applications and collects no money.
2. What needs external integration or real data
- Real university data — via the portal itself, data-sharing agreements, or licensed official sources. No figure is published without a source.
- World rankings — licensed from QS / THE / ARWU with year and source.
- Payments — Stripe for global coverage plus Checkout.com or a regional acquirer for the Gulf (e.g. Tap, HyperPay); webhooks confirm payment.
- Submitting to universities — API, SFTP, or admissions CRM integration (e.g. Slate, Salesforce Education Cloud), or a documented manual export.
- Email & SMS — Amazon SES / SendGrid; Twilio for SMS and OTP.
- FX — a daily provider (e.g. Open Exchange Rates), locked at invoice issue.
- Global statistics — UNESCO UIS and OECD Education at a Glance.
- Live Student Voice sessions — Daily.co or Zoom Video SDK.
3. Proposed technical architecture
WebNext.js 15 · React · TypeScript · Tailwind + Design System tokens · next-intl (RTL/LTR)
APINestJS (Node.js) · REST + OpenAPI · RBAC guards · Zod validation
DataPostgreSQL 16 (Row-Level Security per tenant) · Prisma · Redis cache
SearchMeilisearch / OpenSearch — multilingual, typo-tolerant, faceted
MatchingService in Python/TS: rules engine v1 → learning-to-rank v2 with offline evaluation
JobsBullMQ: notifications, offer expiry, discount thresholds, FX refresh
FilesS3-compatible storage, KMS encryption, ClamAV scan, signed URLs
InfraAWS (me-central-1 + eu + us regions) · Docker · Terraform · CloudFront
Why: Next.js gives SEO-indexable directory pages plus interactive dashboards. NestJS enforces clear modules and server-side permission guards. PostgreSQL Row-Level Security isolates each university’s data in the database itself. Multi-region hosting keeps data near users and meets residency rules.
4. Data model
| Table | Key columns |
|---|---|
| users | id, email, phone, role, locale, mfa, created_at |
| student_profiles | user_id, nationality, dob, study_country, city, school, curriculum_id, grade_scale |
| student_grades | profile_id, term, raw_value, normalized, method_version |
| student_preferences | profile_id, type, ref_id, priority |
| universities | id, names{i18n}, country, city_id, domain, type, verified_at, published |
| university_members | user_id, university_id, role |
| programs | id, university_id, major_id, tuition_minor, currency, years, min_grade, lang_reqs, seats, deadline, data_status |
| taxonomy | faculties ← fields ← majors ← sub_majors (all i18n) |
| applications | id, student_id, program_id, cycle_id, status, submitted_at |
| application_events | append-only log of every status change |
| offers | application_id, conditions, scholarship_pct, expires_at, response |
| ledger_entries | id, kind, amount_minor, currency, beneficiary, status, idempotency_key UNIQUE |
| deposit_credits | deposit_entry_id UNIQUE, state, applied_invoice_id UNIQUE |
| invoices | application_id, fee, credit, discount, due, fx_rate_locked |
| group_offers | program_id, min_students, pct|amount, window, status |
| commissions | group_offer_id, application_id UNIQUE, model, amount |
| ambassadors / questions / appointments | consent_at, withdrawn_at; no exposed contact data |
| settings | versioned key/value (fees, limits, commission, bands) |
| audit_logs | actor, action, entity, before/after, ip, at |
Double-credit prevention: UNIQUE constraints on deposit_entry_id and applied_invoice_id in deposit_credits, updated inside a SERIALIZABLE transaction with SELECT … FOR UPDATE. Money is stored as integer minor units.
5. User flows
| Role | Flow |
|---|---|
| Student | Account → academic → majors (≤20) → regions & countries (≤5) → budget → matches → list (≤5/country, ≤25) → deposit → applications → documents → offers → accept → invoice (− deposit) → enrolled |
| University | Domain-email signup → code → manual review → profile → programs & fees (confirm data) → applications → statuses → offers → group offers → ambassadors |
| Admin | Review verification → publish → fees/limits/commission → taxonomy & geography → payments & refunds → audit |
6. Security, privacy & compliance
- Auth: Argon2id passwords, passkeys, OAuth, and mandatory MFA for university and admin accounts.
- Authorisation: server-side RBAC + Row-Level Security; a university sees only applications made to it.
- Encryption: TLS 1.3 in transit, AES-256 with KMS at rest, field-level encryption for date of birth and phone.
- Payments: card data never touches our servers (provider-hosted fields, PCI DSS SAQ-A scope).
- Privacy: recorded consents, data export and deletion, retention policies; designed for GDPR, UAE PDPL, Saudi PDPL, and FERPA when working with US institutions.
- Minors: students under 18 need guardian consent per local law.
- Operations: daily encrypted backups with point-in-time recovery, immutable audit logs, monitoring, and a penetration test before launch.
7. Assumptions made
- Unified grade is linear (value ÷ scale max) and A-Level letters map to fixed points — an estimate for comparison, not official equivalency.
- “Provisionally eligible” = above minimum with language and curriculum met; “needs review” = within 5 points below, or a language/curriculum gap.
- Programs more than 25% over budget are hidden.
- The deposit is refundable only while its credit is unused.
- Commission is charged once per enrolled student in a program whose group discount has unlocked.
- University enrollment fees are collected by the platform as a collection agent and remitted; direct payment to the university is also supported.
8. Delivery phases
| # | Phase | Status |
|---|---|---|
| 1 | Planning & design: name, identity, architecture, schema, flows, design system, interactive prototype | This prototype |
| 2 | Core product: Next.js + NestJS + PostgreSQL, auth, directory, matching, dashboards | 8–10 weeks |
| 3 | Advanced: live payments, university integrations, discounts & commissions, Student Voice, notifications, reports | 8 weeks |
| 4 | Test & launch: E2E across journeys, RTL/LTR, permissions, payments, performance, pen-test, pilot with 10–20 universities | 4–6 weeks |