Web application¶
The web app is the primary way everyone uses KATE General — managers, teachers, and students all work in the same browser application at kategeneral.long-cao.dev. It is a single-page application served by the same Cloudflare Worker that runs the API, so web and API always ship as one version.
What it is¶
- A React single-page app (React 19 + Vite build + TypeScript). Client-side routing means navigating between screens is instant, with no page reloads.
- Served as static assets by the Worker, with a strict Content-Security-Policy and hardening headers applied to every response (see Security).
- Talks to the API on the same origin (
/api/...) — there's nothing to configure per environment, and no cross-origin setup. - Works on desktop and mobile browsers — the student experience is fully responsive with a mobile bottom-nav.
One app, three role experiences¶
The same app renders a different "shell" depending on who logs in:
| Role | Shell | Feel |
|---|---|---|
| Student | Light shell + mobile bottom-nav (Trang chủ · Bài tập · Lịch sử · AI Tutor) | Simple, homework-focused |
| Teacher | Dark sidebar workspace | Teaching + grading queues |
| Manager | Two full-screen workspaces (operations + academic) with a switcher | Dense, one-task-per-page |
Login is gated: logged-out visitors get a login screen, and each role is kept inside its own area (a student can't reach teacher or admin screens, enforced on the server too).
Notable capabilities¶
- In-browser audio recording for Speaking and read-aloud — the microphone is captured in the browser, uploaded to storage, and transcribed. No plugin or app install needed.
- Distraction-free test mode — while taking a test the app hides all navigation chrome so the student sees only the test; list pages keep the normal navigation.
- Real IELTS-style exam UI — section/passage tabs, an audio player for listening, a question navigator with a timer, review-flagging, and a clickable question grid.
- Rich manager tables and charts — rosters, calendars, tuition ledgers, band-trend charts, and reports, all built for scanning.
- Behavior/integrity capture — time on task, tab-switches, paste attempts, and audio interactions are recorded during tests and surfaced to teachers.
Under the hood (for engineers)¶
| Concern | Choice |
|---|---|
| Framework | React 19, Vite 6, TypeScript (strict) |
| Styling | Tailwind CSS 4 (calm neutral palette, single purple accent) |
| Data fetching / cache | React Query — revisiting a screen serves instantly from cache; mutations invalidate |
| Local state | Zustand (user session, exam state, notifications) |
| Forms / validation | react-hook-form + zod |
| Charts / rich text | Recharts, Tiptap |
Session storage
The login token is currently kept in browser storage and attached to API calls. The per-request account check and the strict CSP close the practical risk; moving the token to an HTTP-only cookie is a planned hardening (see Status & gaps).
How it's built and shipped¶
The web app is built and bundled into the Worker by a single command (npm run deploy) — see Deploy & runbook. There is no separate frontend host, CDN config, or deploy pipeline to manage.