Build notes for Quotient, a gamified cognitive self-insight app: how a two-day build was split into phase-sized pull requests, what the architecture looks like, and why a green `tsc` plus passing unit tests was not enough to notice a broken build.
Quotient is a small cognitive self-insight web app: an adaptive quiz over eight domains, a results reveal, a plain-language report and a chatbot. It is a self-reflection toy, not a clinical test, and I try to say that everywhere it appears. This post is the overview of how it was built; two deeper posts cover the scoring maths and the AI/deployment pieces.
The whole thing was planned as numbered phases, each landed as its own branch and PR:
| Phase | What landed |
|---|---|
| 0 | Next.js + TypeScript + Tailwind scaffold |
| 1 | Prisma schema, migration, seed script |
| 2a / 2b | Adaptive session engine and API routes; unstyled test-taking UI wired end to end |
| 3 | Scoring engine and results page |
| 4a–4d | Theming, page restyle, confetti/sound/streaks, badges and interstitials |
| 5a–5c | Rule-based report, LLMLarge language model — a neural network trained on large amounts of text to predict the next token, used for generation, summarisation, classification and more. rewrite pass, report UI and PDF export |
| 6–9 | RAGRetrieval-Augmented Generation — fetching relevant passages from a document store at query time and handing them to a language model as context, so its answer is grounded in those sources. pipeline, chatbot, dashboard, radar chart, tests |
The point of "unstyled UI wired end to end" in phase 2b is deliberate: get one real answer all the way from a button click to the database and back before spending an hour on styling. Styling is cheap to change later; a wrong data flow is not.
latest resolved to a release candidate.[data-theme] blocks.One small design choice I liked: sound effects are generated with the Web Audio API instead of audio files. I had no licensed sound assets, and a procedural tone is a few lines of code with no download.
This is the part worth being honest about. One session used an automated pass to push a long list of tiny PRs (responsiveness, PWAProgressive Web App — a web app that can be installed and keep working offline, using a web app manifest and a service worker., content, tests). Several of them were not real implementations — they appended comment lines or empty stubs. Two were actively harmful:
globals.css got // line comments appended. Those are not valid CSS, and the PostCSS step failed the whole build.layout.tsx had code appended after the component's closing brace, including a bare navigator.serviceWorker reference that throws when a Server Component is imported.Both slipped through because my checks were tsc --noEmit and the unit tests. Neither builds CSS, and neither complains about unreachable code after a return. The practical result was that the main branch could not deploy for a long run of commits, and the failed preview deploys were quietly using up the free-tier quota.
Recovery was: delete the stub files, fix the syntax, build the real PWA pieces properly (manifest, a cache-first service workerA script the browser runs separately from the page. It can intercept network requests and serve cached responses, which is what makes a web app load offline. for static assets only, explicitly bypassing /api/* because session data is live), and run a real Lighthouse audit instead of writing "score 95+" in a commit message.
pnpm build, not just typecheck and tests.The question bank is small and hand-written, so attempts repeat. The cohort baselines are synthetic. Both are fine for a demo and both are the first things I would fix before anyone treated the numbers seriously.
Building Opener — A File Explorer That Treats AI as Opt-In, Not the Point
Notes from building Opener, an offline-first Android file explorer and editor: the storage seam that made everything else easy, a diff-reviewed AI rewrite flow, folder search built on SQLite FTS5 because Groq has no embeddings API, and the honest call to hide a feature that worked but was too slow.
A Database-Free Content App — Parsing Markdown at Build Time in Next.js (and Doing Attribution Properly)
How the Roadmaps app turns about 94 folders of markdown into a typed, searchable site without a database: a small parser with regexes for resource lines, memoised file-system reads, title-casing rules, and the licensing hygiene of building on someone else's open-source content.
Building Aegis — A Guardrail Gateway You Can Actually Measure
Notes from building a two-tier LLM guardrail gateway and the 127-case red-team harness that scores it — the escalation-router design, a streaming guard that catches leaks spanning chunk boundaries, and the calibration bugs that fell out of actually running it.