How the Zigex student app fits together: what talks to what, how a request travels, and where data and secrets live. Read this before changing anything that crosses a boundary (auth, data fetching, uploads, notifications, deploys).
Last reviewed: 8 October 2026 (v1.0.0). Update it when a boundary changes, in the same pull request.
flowchart LR
student["Student<br/>(phone / laptop browser, installable PWA)"]
subgraph vps["Zigex VPS"]
nginx["Nginx<br/>HTTPS, gzip, static cache"]
prod["Student app · production<br/>Next.js 16 standalone · PM2 'zigex' :3000"]
dev["Student app · development<br/>PM2 'zigex-dev' :3100"]
end
api["Zigex backend API<br/>api.zigexconnect.com<br/>(Express + Prisma + Postgres)"]
ai["Zigex AI service<br/>ai.zigexconnect.com<br/>(digests + document search)"]
admin["Admin app<br/>(companies & supervisors, separate repo)"]
r2["Cloudflare R2<br/>photos, covers, CVs"]
supa["Supabase Storage (legacy)<br/>opportunity flyers, logos"]
sanity["Sanity<br/>blog / announcements CMS"]
google["Google Identity<br/>sign-in"]
push["Browser push services<br/>(FCM, Mozilla…)"]
mail["Gmail SMTP · EmailJS · Resend<br/>emails"]
discord["Discord (WidgetBot)<br/>community chat"]
student -- HTTPS --> nginx
nginx --> prod
nginx --> dev
prod -- "REST + JWT (server side)" --> api
admin -- "REST" --> api
prod -- "x-api-key (server side)" --> ai
ai -- "student profiles" --> api
admin -- "X-Internal-Key: push trigger" --> api
api --> r2
api -- "Web Push (VAPID)" --> push
push --> student
prod --> sanity
prod --> mail
student --> google
student -. "images" .-> r2
student -. "images" .-> supa
student -. "embed" .-> discord
| Part | What it is | Owned by |
|---|---|---|
| Student app (this repo) | Next.js 16 (App Router, React 19, Tailwind v4). Renders every page, keeps the session cookie, forwards API calls. No database of its own. | Frontend team |
| Backend API | https://api.zigexconnect.com, Swagger at /api-docs. All data: students, opportunities, applications, notifications, uploads, push. |
Backend team |
| Admin app | Separate repo (zigex-admin). Companies post opportunities and review applications; supervisors manage interns. Talks to the same backend. |
Frontend team |
| AI service | https://ai.zigexconnect.com, Swagger at /docs, repo zigxconnect/zila-knowledge-base-with-search (FastAPI + Celery + Redis + Qdrant, Gemini for embeddings and the LLM, Tavily for web search). The signed-in feed requests a per-student recommendation through POST /v1/digests/student/{id}/recommendation; expensive work is queued and cached in Redis. A separate weekly batch path can still build broader department/location digests. The service also searches documents uploaded per department slug + cohort_id (convention: internship or program id). This app calls POST /v1/search for document search in the workspace Learning tab. Its API key stays on the server (lib/api/ai-service.ts). See Personalized recommendations for the full request flow, issue history, privacy boundaries, and 100-student scaling behavior. |
Backend team |
| Cloudflare R2 | File storage behind the backend. Public files (avatars, covers) by URL; private files (CVs) through signed URLs. | Backend team |
| Supabase Storage | Legacy storage still holding older opportunity images and company logos. Read-only from this app. | Legacy |
| Sanity | CMS for announcements/blog. Studio at /studio. |
Content team |
| Gmail (Nodemailer) for application emails, EmailJS for the welcome email and waitlists, Resend for the contact form. See setup/email.md. | Frontend team |
Browser
│ pages (HTML + React Server Components) fetch("/api/v1/…") (client components)
▼ │
proxy.ts ── who may see this page? (reads the session cookie, redirects) │
▼ ▼
Server Components / Server Actions app/api/v1/[...path] (passthrough)
│ lib/api/services/* (domain logic) │ adds Authorization: Bearer <JWT from cookie>
│ lib/api/server-client.ts (serverApi) │ stores the token on sign-in, clears it on sign-out
└──────────────► Backend API ◄──────────────────────┘
Layers (top calls bottom, never the other way):
| Layer | Where | Rule |
|---|---|---|
| Pages and layouts | app/**/page.tsx, layout.tsx, loading.tsx, error.tsx |
Fetch through services; keep markup in components |
| Components | components/<feature>/… |
Presentational or interactive; client components call lib/api/*-client.ts |
| Services (server) | lib/api/services/*.ts |
One file per domain (feed, applications, profile, programs…). Server-only (import "server-only") |
| Browser clients | lib/api/*-client.ts |
The same domains for client components, through /api/v1 |
| Shapes | lib/api/*-shape.ts |
Turn backend responses into what the UI expects. The only place that knows the backend's field-name quirks. |
| HTTP | lib/api/server-client.ts, lib/api/browser-client.ts, lib/api/errors.ts |
Timeouts, ApiClientError, whenAvailable() for endpoints that may not exist yet |
Route groups (folders in parentheses don't appear in URLs):
| Group | Pages | Access |
|---|---|---|
(main) |
landing /, /privacy |
Public; signed-in students are sent to /feed |
(public) |
/feed, /feed/[id], /company/[id] |
Public, shareable |
(auth) |
sign-in, sign-up, verify-email, forgot/reset/update password | Public; signed-in students are sent on |
(onboarding) |
/create-profile, /profile-complete |
Signed in |
(dashboard) |
Programs, My applications, Announcements, Students, profiles, Communities, Notifications, Settings, Edit profile, Zila, intern workspace | Signed in; shared shell (sidebar, header, mobile tab bar) |
| other | /studio (Sanity), /attendance/scan, /offline (PWA fallback), /projects |
Mixed |
Legacy pages still in the tree, not linked from the main navigation: /dashboard/job-stores, /dashboard/viewpage, /dashboard/track-progress, /dashboard/company, /dashboard/projects, /demo, /internships, /events. Candidates for removal.
Students with an accepted placement get a workspace (/student/workspace; /intern/workspace is the same). It's the most-used page during an internship, so it's built around the working day.
| Piece | Where | What it does |
|---|---|---|
| Entry and routing | app/(dashboard)/student/workspace/page.tsx, lib/workspace/routing.ts |
Opens the right placement: the one asked for (?appId=), else the one running now, else the one starting soon; a list grouped Current / Starting soon / Finished only when several run at once (?all=1 forces the list). |
| Data | getInternshipWorkspaceData in lib/actions/intenship.actions.ts, lib/api/services/workspace.ts, attendance.ts |
Placement (full posting loaded when the backend embeds a stub), daily logs, tasks, announcements, team, curriculum. |
| Rules | components/workspace/workspace-model.ts |
Pure functions: today's state, the attendance calendar, placement phase (upcoming, current, finished), task sorting and due labels. No React, easy to test. |
| Page | components/workspace/WorkspaceView.tsx and siblings |
Header, Today panel (or "has ended"), tabs (Overview, Tasks, Reports, Updates, Learning, Payments), dialogs. |
| Check-in | components/sections/intern/AttendanceQRScanner.tsx, StandaloneQRScanner.tsx, components/workspace/CheckInResult.tsx, app/attendance/scan |
Camera scan in the app, or the poster opened by the phone's own camera. A test mode before day one records nothing. |
| Documents | app/api/internships/logbook/…, receipt/…, lib/documents/document-html.ts |
Printable logbook and receipts. Uses the backend's PDF if it sends one, else renders HTML from JSON. Every value is escaped. |
A working day is one log row on the backend: check-in opens it, the daily report (check-out) closes it. The supervisor's tools (tasks, report approval, QR posters, payments) live in the admin app; see product/admin-side-handoff.md.
sequenceDiagram
participant B as Browser
participant P as Student app (/api/v1)
participant A as Backend API
B->>P: POST /api/v1/auth/login {email, password}
P->>A: POST /api/v1/auth/login
A-->>P: { token, user }
P-->>B: Set-Cookie zx_access_token (httpOnly, SameSite=Lax, Secure in production)<br/>body without the token
B->>P: GET /dashboard/programs (cookie sent automatically)
Note over P: proxy.ts decodes the JWT (no signature check)<br/>only to decide redirects
P->>A: GET /api/v1/... Authorization: Bearer <token>
Note over A: verifies the signature on every request
- The token never reaches JavaScript. It lives in the httpOnly cookie
zx_access_token; the passthrough (app/api/v1/[...path]/route.ts) adds it as a Bearer header. Token-issuing paths:auth/login,auth/verify-email,auth/reset-password,auth/google. proxy.tsis for routing, not security. It reads the JWT payload without verifying it (lib/api/jwt.ts) to redirect signed-out visitors to/sign-in?next=…and non-students to the admin app. The backend verifies every data request, so a forged cookie only gets 401s.- Return after sign-in:
?next=is checked bylib/utils/redirect.ts(relative paths on an allow-list; no//, backslashes or protocols). - Google sign-in: Google Identity Services gives an ID token;
POST /auth/googleexchanges it for our JWT. Our styled button has Google's real button invisibly scaled over it (components/sections/auth/GoogleSignInButton.tsx). - Roles: the app is for
student. Company/supervisor accounts are redirected to the admin app (NEXT_PUBLIC_ADMIN_APP_URL).
The backend answers in 0.5–1.5 s, so the app avoids calls rather than waiting for them.
| Technique | Where | Effect |
|---|---|---|
Per-request dedupe with React cache() |
getMyProfile, fetchMyApplicationRows, getFeedItemById |
One /students/me and one /applications per page, however many components need them |
Shared public cache (fetch with next: { revalidate: 120 }, no token) |
listPublicFeed, getPublicFeedItem, latestFeed |
Explore lists, opportunity details and "more from this company" are cached 2 minutes for everyone |
| Parallel fetches | Promise.all in pages (e.g. opportunity page: prefill + status) |
No waterfalls |
| Streaming | loading.tsx per page (page-shaped skeletons), <Suspense> around secondary sections |
The page appears before slow parts finish |
| Image optimisation | components/CoverImage.tsx → next/image for allowed hosts |
A 394 KB flyer becomes a 44 KB WebP on phones |
| Fewer background calls | Notification bell polls every 60 s only while the tab is visible; push subscription re-synced once a day | Less load on the backend |
Signed-in data is always cache: "no-store" (it's personal). Only public, token-free data is shared-cached.
Pick photo → crop dialog (1080 px square) → resize/re-encode in the browser (JPEG, ~150–400 KB)
→ base64 JSON → POST /api/v1/uploads/avatar (passthrough, 60 s timeout) → backend → R2
→ returns the public URL → PATCH /students/me { avatarUrl } → page refresh
- Resizing happens before upload (
lib/api/uploads.ts): avatars 1080 px, covers 2400 px. CVs (PDF/.doc, 5 MB) go to/uploads/resume/{applicationId}after the application exists. - Every displayed image goes through
usableImageUrl()(lib/images.ts), which hides known-bad hosts and, temporarily, rewritesfiles.zigexconnect.comto the bucket'sr2.devaddress until that domain has DNS.SafeImghides broken images so initials show instead.
sequenceDiagram
participant C as Company (admin app)
participant AB as Admin backend
participant API as Backend API
participant PS as Push service (FCM…)
participant S as Student browser
C->>AB: accept application
AB->>API: POST /internal/push/trigger (X-Internal-Key)
API->>API: store notification (deduped 10 min)
API->>PS: Web Push (VAPID private key), tag, TTL
PS->>S: push → public/push-sw.js shows it
S->>S: tap → opens notification url (same-origin only)
S->>API: (via /api/v1) GET /notifications, unread-count
- Students turn push on in Settings (never prompted on page load). The app subscribes with
NEXT_PUBLIC_VAPID_PUBLIC_KEYand sends the subscription toPOST /push/subscriptions. An old-key subscription is replaced automatically (lib/push-keys.ts). - The bell and
/notificationsusenotificationHref()(lib/notifications.ts): the backend'surlwhen it's a local path, otherwise a link worked out from the type. Duplicates are merged. - Global notifications (sent to everyone) created before the student's account are hidden in the app, in the list and in the unread count, until the backend filters them itself.
- Event list, wording and links: backend/notifications.md.
| Situation | What the student sees | Where |
|---|---|---|
| A page can't load (slow/failed backend) | "This page didn't load" + Try again (refetches) + reference code; offline variant retries when back online | app/error.tsx, app/(dashboard)/error.tsx, app/global-error.tsx → components/errors/ErrorScreen.tsx |
| An action fails (apply, upload, delete) | Specific message next to the button (offline / slow / signed out / closed / try again) | e.g. components/apply/ApplyDialog.tsx |
| An endpoint isn't deployed yet | An empty or "coming soon" state, not an error | whenAvailable() / isEndpointMissing() in lib/api/errors.ts |
| Missing page | app/not-found.tsx |
Catch blocks that log errors call unstable_rethrow(error) first so Next.js's own signals (redirects, "render per request") pass through.
| Development | Production | |
|---|---|---|
| URL | dev.zigexconnect.com |
zigexconnect.com |
| Deployed from | every push to zigex |
version tags vX.Y.Z |
| On the VPS | /home/zigex/apps/zigex-dev, PM2 zigex-dev, :3002 |
/home/zigex/apps/zigex, PM2 zigex, :3200 (not switched yet) |
| Indexing | blocked (NEXT_PUBLIC_APP_ENV=development) |
allowed |
| Backend | same API (real data) | same API |
flowchart LR
pr["Pull request"] --> ci["CI: type check, build, audit"]
ci --> merge["merge to zigex"]
merge --> devdeploy["Deploy → development"]
merge --> tag["npm version + push tag"]
tag --> gate{"same commit passed CI<br/>and deployed to dev?"}
gate -- no --> stop["stop"]
gate -- yes --> build["build on GitHub"] --> upload["upload to VPS"] --> switch["switch release"]
switch --> health{"health + smoke test"}
health -- fail --> rollback["automatic rollback"]
health -- pass --> live["live + GitHub Release"]
The VPS is shared with other apps; its exact setup (user, Node through nvm, admin-managed Nginx, ports) is in setup/server.md.
Build output is Next.js standalone (server.js + traced node_modules); releases are folders releases/<version>_<timestamp> with a current symlink, so rollback is a symlink switch. Details: setup/deploy.md.
- Build-time, public:
NEXT_PUBLIC_*values are baked into the browser bundle. Set in GitHub Variables (per environment). Never put a secret behindNEXT_PUBLIC_. - Runtime, private: everything else (
JWT_SECRET,AI_SERVICE_API_KEY,GMAIL_*,EMAILJS_PRIVATE_KEY,RESEND_API_KEY,SANITY_WEBHOOK_SECRET…) lives only in each site'sshared/.envon the VPS, loaded by Node's--env-file. - Shared with other systems:
JWT_SECRETmust match the admin app (attendance QR codes are signed there and checked here). The VAPID public key must match the backend's pair. - Full list with meanings:
.env.exampleand README.
- Headers (
proxy.ts):X-Frame-Options: SAMEORIGIN,X-Content-Type-Options: nosniff,Referrer-Policy,Permissions-Policy(camera=(self)for the check-in scanner,geolocation=(self)for check-in location; everything else off). No CSP yet (candidate). - Stored HTML (company descriptions, announcements, program updates) goes through
safeHtml()(lib/safe-html.ts, sanitize-html) insideRichContentRenderer. Never render backend HTML withdangerouslySetInnerHTMLdirectly. - Documents (logbook, receipts) are HTML built from backend data: every value goes through
esc()inlib/documents/document-html.ts. - Open redirects:
?next=and notification links only accept local paths. - Push: the service worker only opens same-origin URLs. The push trigger is backend-to-backend with a shared key.
- Files: CVs are private (signed URLs); uploads are size- and type-checked in the browser and by the backend.
- The app trusts the backend for authorisation. Never decide permissions in the frontend alone.
- 51 TypeScript errors in older pages; type check is report-only in CI and
ignoreBuildErrorsis on. - No automated tests yet (the smoke test checks pages after each deploy).
- Temporary workarounds: the
files.zigexconnect.comrewrite (lib/images.ts); stub-posting hydration (lib/api/applications-shape.ts, also used by the workspace and documents); hiding global notifications older than the account (lib/api/notifications-client.ts); counting an accepted application as "intern" whenis_internis false (lib/actions/profile.actions.ts). Each has an item in backend/open-requests.md. - Security updates pending:
html2pdf.js(critical),nodemailer(high). - Development and production share one backend, so testing on dev uses real data.
- Open backend requests: backend/open-requests.md.