Welcome KKU Freshmen 2026 (KKU63)

What it is built on

• Next.js 16 + React 19 — App Router, server actions for every write, bilingual through next-intl
• MUI 9 — carried over from the 2024 and 2025 builds, so it was not a new library to learn mid-project
• React Hook Form + Zod — one schema validates the form and the write to Firestore
• Firebase — Firestore, Auth, Storage; server code uses the Admin SDK only, client code is limited to bounded reads
• Vercel — deployed at kku-63.vercel.app, signed into mostly through the university's own OAuth

Keeping Firestore reads bounded

8,500 and 500 are not decoration in the docs — they are multipliers. A participant page that reads 20 documents becomes roughly 170,000 reads once every freshman opens it; a staff page that reads 500 becomes roughly 250,000 once the whole team does. Query shape is therefore treated as a correctness concern rather than something to tune at the end.

• A page showing one person's data queries by that person's key, rather than reading a collection and filtering in memory
• Every list view carries orderBy and limit, with cursor pagination wherever the data can grow
• Profile joins use chunked byIds helpers, reusing one map across a request instead of reading the same rows twice
• E-ticket running numbers come from a counter document inside a transaction at event/{eventId}/counters/e-ticket, not from counting the event's tickets, with a test for concurrent check-ins
• Reference data that barely changes — kku-location, event — sits behind a service-level cache
• Every staff write goes through a server action on the Admin SDK behind one shared guard; no CRUD is issued straight from the client SDK

Rules that enforce themselves

Writing a narrow query is an afternoon's work. Keeping it narrow is not something good intentions hold, because listServerUserPublic() and a filter afterwards is always the shorter thing to type. So the point was to make that not pass.

web/scripts/firestore-guard.mjs      blocks listServerX() outside an allowlist
web/eslint.config.mjs                server-only code cannot import client repositories
web/AGENTS.md                        the short mandatory rules, for AI agents
docs/firestore-query-knowledge.md    the rationale, examples and decision tree
docs/firestore-read-guardrails.md    the checklist used when reviewing a PR

The guard's allowlist names each path that is genuinely allowed to read a whole collection, with its reason beside it. Adding to it became a decision somebody has to defend rather than a line somebody types.

If the answer is “read all documents and filter in memory”, the default answer is no for participant and staff hot paths.

The PR checklist asks the same questions every time — if this collection grows 10x, is the query still bounded, and is the code reading these documents because the UI needs them or because there is no narrower repository method yet.

Closed for good

The site was permanently retired on 2 August 2026 once the week was over. main is locked behind maintenance mode and a separate demo branch exists to run it, carrying a bold note not to merge it back and not to expose it publicly until it points at a demo dataset — because this project is wired to a database holding real student records, drug allergies, food allergies and chronic conditions included.

Fourth year building this system, and the first with tests, with the reasoning behind its decisions written down, and with tooling that refuses the old mistakes on its own rather than waiting for somebody to remember them.