Vercel frontend + Portal API + Neon PostgreSQL

flowchart TB
  user(["Browser"])
  team(["Raisd team"])

  subgraph gh ["GitHub · raisd-campus"]
    repos["Portal repos
ci-cd.yml"]
    apirepo["portal-api
ci.yml (checks)"]
    pkg[("GitHub Packages
@raisd-campus/design-system")]
    pages["portal-api-docs
GitHub Pages"]
  end

  subgraph vercel ["Vercel team · Singapore sin1"]
    land["raisd-campus-landing
Lesotho chooser"]
    sp["raisd-student-portal
static SPA"]
    ap["raisd-applicant-portal
static SPA"]
    lp["raisd-lecturer-portal
placeholder"]
    stp["raisd-staff-portal
placeholder"]
    api["raisd-portal-api
Node 22 function · Fastify
Student + Applicant Demo engines"]
    dba["raisd-db-admin
read-only · sign-in"]
  end

  subgraph neon ["Neon · aws-ap-southeast-1"]
    db[("neondb · Postgres 18 · schema v4
record tables · 4 views · audit_events
student_portal_state · applicant_portal_state
portal_meta · poc_sessions · poc_applicant_sessions")]
  end

  subgraph prod ["Production — not part of this PoC"]
    cms[("Cyberjaya CMS
system of record · ADR-1")]
    ulta["UltaHost Singapore + k3s
ADR-2 / ADR-3 · SDD-12"]
  end

  user -- HTTPS --> land
  land --> sp
  land --> ap
  land --> lp
  land --> stp
  user --> sp
  user --> ap
  user --> lp
  user --> stp
  sp -- "PortalApi RPC · bearer
VITE_PORTAL_API_URL" --> api
  ap -- "ApplicantPortalApi RPC · bearer
VITE_PORTAL_API_URL" --> api
  pages -. "Swagger Try it out" .-> api
  api -- "DATABASE_URL (pooled, TLS)" --> db
  team -- "sign-in (session cookie)" --> dba
  dba -- "raisd_db_admin_reader
READ ONLY" --> db
  repos -- "npm ci" --> pkg
  repos -- "vercel deploy --prebuilt" --> sp
  team -- "npm run deploy:vercel" --> api
  sp -. never .-x db
  api -. no Live writes .-x cms

  classDef poc fill:#e8f0f8,stroke:#1a4f8b,color:#152033
  classDef store fill:#eef7ee,stroke:#2f7d32,color:#152033
  classDef out fill:#f6f6f6,stroke:#9aa5b1,color:#5a6a7e,stroke-dasharray:4 3
  class land,sp,ap,lp,stp,api,dba poc
  class db,pkg store
  class cms,ulta out
        

flowchart LR
  subgraph portals ["Portal repos · ci-cd.yml"]
    pr1["Pull request"] --> chk["Check
npm ci · lint · test · build"]
    push1["Push to main"] --> chk
    chk -- "main only" --> dep["Deploy
build Vercel output
vercel deploy --prebuilt --prod"]
    dep --> v1(["raisd-<repo>.vercel.app"])
  end
  subgraph api ["portal-api · ci.yml"]
    pr2["PR / push to main"] --> smoke["Checkout api + student-portal + control-plane
npm ci · docs:check · boot + smoke"]
    dev(["Developer laptop"]) --> man["npm run deploy:vercel"]
    man --> v2(["raisd-portal-api.vercel.app"])
  end
  subgraph docs ["portal-api-docs · pages.yml"]
    push3["Push to main"] --> lint["Redocly lint openapi.yaml
validate design-system pages"]
    lint --> pub["Assemble _site + site auth
deploy-pages"]
    pub --> v3(["GitHub Pages"])
  end
  dev --> man2["npm run deploy"] --> v4(["raisd-db-admin.vercel.app"])
        

erDiagram
  RECORD_TABLE {
    text id PK "record id"
    integer position "fixture order"
    jsonb record "source of truth"
    timestamptz updated_at "last write"
    generated fields "one column per top-level field"
  }
  student_portal_state {
    text student_profile_id PK
    jsonb personal_profile
    jsonb resume_profile
    jsonb portfolio_profile
    jsonb finance_payment_proofs
    jsonb chat_store
    timestamptz updated_at
  }
  portal_meta {
    boolean id PK "single row"
    bigint revision "+1 per record write"
    timestamptz seeded_at
    text_array collections
  }
  poc_sessions {
    text token_hash PK "sha256 hex of the bearer token"
    text scenario_id "Demo student scenario"
    text student_profile_id "profile for the scenario"
    timestamptz created_at "default now()"
    timestamptz expires_at "created + 12 h (indexed)"
    timestamptz revoked_at "set on logout, else null"
  }
        

sequenceDiagram
  autonumber
  actor S as Student
  participant SP as Student portal (Vercel static)
  participant API as Portal API (Vercel function)
  participant DB as Neon poc_sessions
  S->>SP: Student number + password
  SP->>API: POST /v1/auth/login {scenarioId, password}
  API->>API: Validate body, constant-time password check
  alt wrong password
    API-->>SP: 401 "Student and password do not match."
  else ok
    API->>DB: create table if not exists (first use)
    API->>DB: insert token_hash, scenario, profile, expires_at
    API-->>SP: 200 {accessToken, expiresIn 43200, scenarioId, studentProfileId}
    SP->>SP: Keep bearer token for the session
  end
        

sequenceDiagram
  autonumber
  participant SP as Student portal
  participant API as Portal API instance
  participant DB as Neon
  participant M as MockPortalApi (per request)
  SP->>API: POST /v1/portal/submitOnlineForm {args} + Bearer
  API->>DB: poc_sessions lookup by sha256(token)
  alt no row
    API-->>SP: 401 Session expired or missing
  else session found
    API->>DB: portal_meta revision + student_portal_state row
    opt cache is not at seeded_at + revision
      API->>DB: read all record tables (one read-only snapshot)
    end
    API->>M: fresh engine over the records for scenario_id
    M-->>API: result (+ changed records / student state)
    opt method wrote
      API->>DB: begin · lock portal_meta · revision unchanged?
      API->>DB: upsert / delete changed rows · revision + 1 · upsert student state · commit
      Note over API,DB: revision moved → reload and rerun (3 tries, then 409)
    end
    API-->>SP: 200 {result, cms: {acknowledged: true, mode: "stub"}}
  end
        

sequenceDiagram
  participant SP as Portal
  participant API as Portal API
  participant DB as Neon
  SP->>API: POST /v1/auth/scenario {scenarioId} + Bearer
  API->>DB: update scenario_id, student_profile_id
  API-->>SP: 200 {scenarioId, studentProfileId}
  SP->>API: POST /v1/auth/logout + Bearer
  API->>DB: update revoked_at = now()
  API-->>SP: 200 {ok: true}
        

sequenceDiagram
  actor Dev as Developer
  participant GH as GitHub (portal repo)
  participant GA as GitHub Actions ci-cd.yml
  participant PK as GitHub Packages
  participant V as Vercel
  Dev->>GH: merge / push to main
  GH->>GA: push event
  GA->>PK: npm ci (@raisd-campus/design-system via GITHUB_TOKEN)
  GA->>GA: lint · test · build
  GA->>GA: build .vercel/output (VITE_PORTAL_API_URL baked in)
  GA->>V: vercel deploy --prebuilt --prod (VERCEL_TOKEN)
  V-->>GA: deployment URL, alias raisd-<repo>.vercel.app