Thnkrr: Plug-and-Play Check and Server Load

10 October 2026. An investigation of the code on the dev/pilot branch (API at merge commit 225d7f9, web at 67e8c47). Nothing is built or changed here. This is findings plus a plan that waits for approval.

It answers three questions:

1. Can every outside supplier be swapped by changing settings and copying data, without rewriting the app and without rewriting the rows already in the database?
2. Is the code modular, and are the database tables kept apart cleanly enough that one part can be replaced without dragging the others along?
3. What does each student action cost the server, what happens at 3,000 to 5,000 daily active users, and where can the load be cut?

The companion files are PROVIDER-SWAP-RESEARCH-2026-10-09.md (which supplier could replace which, with prices) and PRODUCTION-PLAN-2026-10-09.md. This document looks at the code itself, which those two did not do in detail.

The one-minute version

• The suppliers that touch student data are all behind connectors, and swapping any of them never needs a data migration. Files, email, the AI writing check, the guardian adult check and the job queue each sit behind one small interface, and the database stores only neutral values (file names, not Amazon addresses; the model's name, not Amazon's format). Tests prove each connector daily with a fake. This is the good news and it is most of the picture.
• Three gaps on the supplier side: the picture check the documents describe does not exist in the code at all; video conversion calls ffmpeg directly with no connector; and the delivery-network purge has only an Amazon version. None is urgent for the pilot. The first two are one to two days each.
• The database tables are well separated. Ten files, one per area, and the areas point at each other through neutral "what kind of thing, which one" pairs rather than hard links. Four small pieces of debt are listed in section 5.
• The code's modules are reasonably separate but not independent. The profile module reaches into nine others, and there are a few two-way dependencies. This does not block any supplier swap. It would make splitting the app into separate services slow, which nobody is asking for.
• Server load is the real finding. At 5,000 daily active users the database would see roughly 900 to 1,000 questions a second at peak with today's code, and about three quarters of that is waste: every request asks the database three times just to learn who is signed in, every open browser tab asks for notifications and messages every 30 seconds, and a reviewer's queue page asks the database several hundred questions every 5 seconds. Six targeted changes bring the peak to roughly 200 a second, which the smallest database size handles with room to spare.
• The AI check is cheap at this scale: about 7,500 checks a day, roughly $25 a month. Photos and videos are the part that would hurt a 2-processor server: video conversion and speech-to-text could use 4 to 7 hours of one processor a day, on the same machine that answers students. The fix is to run that work in a second process, which the code is already shaped for.
• Six things assume one server. Rate limits, the posting brake, the search gate, the AI throttle, the busy-cache and the term cache all live in the memory of one process. A second API server would double every limit silently. Fine for the pilot, must be fixed before a second server.

Words used in this document

1. What we checked and how

Every source file of the API (118 files, about 30,000 lines) and the web app on dev/pilot was read, by hand or by three parallel read-only audits. For each outside supplier we asked: is there one interface, how many implementations, is a fake used in tests, and what does the database store about it. For each route a student or a reviewer hits we counted the database queries, looked for loops that query per row, for missing indexes, and for timers in the browser. For each background job we counted what it does every tick when there is nothing to do.

Numbers come from reading the code, not from running it under load. The projections in section 8 use stated assumptions and are estimates to within a factor of two.

2. Outside services, one by one

"Swap" says what a change of supplier takes with the code as it is today. "Rows" says whether the database would need rewriting.

Leak check. No Amazon, Bedrock, S3, CloudFront, whisper or SMTP library is imported outside the connector files, with one exception: the sharp image library is used directly in the media and evidence modules and the seed scripts. That is fine; it is open software doing image work, not a supplier. The web app contains no supplier name at all. Its only assumption is that a video upload returns an ETag header, which every S3-speaking service does.

Where connectors are created. The app hands four connectors to every module through one shared context object: database, jobs, mailer, classifier, storage. Three others are built on the spot from settings inside the module that uses them: the transcriber, the purge, the adult check. It works, but it is inconsistent, and the on-the-spot ones cannot be faked in a test. Cheap to unify.

3. The database: are the tables well separated?

Yes. The 55 tables live in ten files, one per area: identity, profiles, social, moderation, mentorship, safety, care, consent, handles, school pages.

What keeps them apart:

• Neutral pointers. Notifications, reports, the audit log, content reviews, case actions, evidence files and deadline alerts each say "what kind of thing, which one" as two plain columns. They do not hard-link to the posts or messages tables. So the moderation area can review a new kind of content without the posts area changing, and vice versa.
• Staging in the review row. Profile text, school descriptions and mentor experience descriptions are held in the review row until approved. The live table only ever carries approved text. One pattern, used everywhere.
• No supplier shapes. The AI verdict is stored as our own small JSON (decision, categories, confidence, reason) plus the model's name, not Amazon's response format. File columns hold names. The adult-check column holds "provider:reference".
• Current state in one place, history elsewhere. School membership is "current rows only", with a separate history table. Consent is append-only. Author holds are never deleted.

A supplier swap never requires a data migration. Checked for files, email, the AI check, the delivery network, speech, the adult check and the queue.

Debt worth clearing, none urgent:

4. Is the code modular?

Reasonably, with a hub. Nineteen modules under src/modules, each with its own routes and service files, all talking to the outside world through the shared context.

What this means in practice: any supplier can be replaced without touching modules; any module can be changed without touching suppliers; but pulling one module out into its own service (for example running moderation on its own machine) would take real work because of the two-way links. Nobody has asked for that, and the pilot does not need it.

5. Server load today: what each action costs

Every signed-in request first pays a fixed cost: three database queries to turn the cookie into a person (session, then user, then roles). The cookie itself is not checked by signature, only by lookup. Counts below include those three.

What a student does

The AI prompt is about 1,040 words-worth of policy sent in full on every call (no caching on the Bedrock path), plus the text and up to 10 prior messages for a thread. One call per item, not per field: a post's body, link, photo captions and transcript are joined and checked once.

What the browser does on its own

Polls pause when the tab is hidden, with three exceptions that keep running: the photo editor's refresh, the consent waiting screen (every 5 s, unbounded) and the upload status loop.

What the server does with nobody around

Missing indexes that the hot paths want

Numbers in settings that do not fit a 2-processor, 4 GB server

6. Things that assume one server

All of these live in the memory of the process. A second API server would not know about the first.

Already safe for many servers: item locks (Postgres advisory locks), deadline alerts (unique rows), care reminders (conditional updates), scheduled jobs (pg-boss runs each once).

7. At 3,000 to 5,000 daily active users

Assumptions (change any of them and the numbers scale in proportion): 5,000 people a day; a school day of about 8 hours; 10 to 15 percent of them with the app open at the same moment at peak, call it 600 tabs; each person opens about 15 pages, writes 1 to 2 things, opens 1 profile and uploads a photo one day in ten; 50 videos a day across all schools; 5 reviewers working with a queue of about 50 items.

Database questions per second at peak, with today's code

Three quarters of that is the three sign-in queries on every request plus the two polls and the reviewer fan-out. A small Postgres can answer 950 simple questions a second, so this does not fall over on day one. It gets worse with time, not with users:

• The reviews table grows by about 7,500 rows a day (2.7 million a year). The stats call counts the whole table every 10 s per reviewer. The nine lookups by subject id read the whole table each. Within months these become seconds each.
• The messages preview reads every message a person has ever exchanged. It grows with history forever.
• The users-table read every minute for suspensions grows with sign-ups.

What breaks first, in order: the reviewer pages (they slow down as the reviews table grows, and they are polled every 5 s); then the 10-connection pool during a lunchtime posting burst, when 300 AI checks each want a connection and students start seeing "busy"; then the database's burst credits on the smallest instance size.

Processor time on the API server

Outside services and money

The AI is not the cost driver at this scale. The database and the one server's processor are where the ceiling is.

8. How to reduce the load, ranked by payoff

Each row says what changes for a student, roughly how much it saves, and how big the change is. None is built. None changes any supplier.

After ranks 1 to 5, the same peak is roughly 200 database questions a second, dominated by real page opens. That fits the smallest RDS size (db.t4g.micro) with headroom; db.t4g.small is the safe choice if the reviewers' tables keep their full history online.

9. The plan

Nothing here is built. Order is by payoff and by what unblocks the next step. Effort is agent days.

Phase A: load, before more schools (about 5 days)

1. Sign-in check to one query plus a short cache (rank 1).
2. The seven indexes (rank 5).
3. Messages preview as one row per thread (rank 4).
4. Badges call and 60-second tick (rank 2, first half).
5. AI concurrency and pool numbers fitted to the pilot (rank 7).
6. Idle job polls slowed (rank 9).

Gate: a load replay (the existing moderation:load script extended with feed, notifications and messages traffic at 600 simulated tabs) shows under 300 database queries a second.

Phase B: reviewers and workers (about 4 days)

1. Reviewer queue without fan-out, running counters for stats, lists mounted per tab (rank 3).
2. Worker role split (rank 6), with the deploy script starting two services.
3. Feed and publish-path trims (rank 8).

Gate: a full queue of 100 items opens in under half a second; a 15-minute video converts without any student request waiting on the database.

Phase C: plug-and-play gaps (about 5 days)

1. Picture-check seam with a "send to a person" default and one adapter (the research recommends starting with Google Vision SafeSearch or Azure Content Safety on data terms).
2. Transcriber, purge and adult check handed in through the shared context like the others, so each can be faked in tests.
3. A second purge adapter (Cloudflare) beside CloudFront.
4. A video-conversion interface around the ffmpeg calls, with ffmpeg as the one implementation, so a cloud converter is an adapter, not a rewrite.
5. The web app consumes @thnkrr/contracts directly instead of a hand-copied mirror.

Gate: every connector has a fake, a conformance test and at least one real implementation.

Phase D: before a second server (about 3 days)

1. Rate limit, posting brake, search gate and AI throttle moved to a shared store. Postgres can hold them (a small counters table with the advisory-lock pattern already in use); no Redis needed at this scale.
2. Push channel for notifications and messages (rank 2, second half).

Gate: two API processes behind one address pass the integration suite with the same limits as one.

Schema clean-up (any time, half a day)

Drop the deprecated domains column and the five unused tables in one additive-then-drop migration pair, after a backup.

10. The founder's answers

• Badge refresh: stays at 30 seconds. The new badge call is cheap enough that slowing it down isn't needed.
• Archive: not built. Keeping every review in the main tables is fine at pilot size now that the slow lookups have indexes. If an archive is ever added, archived reviews must still open on screen on demand.
• A small server for video: yes, but after the current version is deployed. The switch is built (section 11); the second server is not.

11. What was built (10 October 2026)

Everything in phases A, B and C plus the schema clean-up, on branch feat/load-and-seams in both repos. Phase D (a second API server) was left out by decision. Pull requests into dev/pilot: thnkrr-api #18, thnkrr-web #16.

Measured results

Database questions per call, warm, on a busy test account. "Before" was measured on dev/pilot before any change.

In the browser, pages open in 130 to 290 milliseconds and taps answer in 100 to 150 milliseconds on the busy account. Nothing froze for more than 70 milliseconds.

One audit item turned out wrong

The audit said 300 AI checks in flight would starve the 10 database connections. A real burst of 2,000 posts said otherwise: student reads stayed at 1 to 2 milliseconds and nobody was told "busy", because a check doesn't hold a connection while it waits for the AI. Lower settings only made the burst five times slower, so the settings were left alone.

A second item was withdrawn: the review page loads every staff list because its main tab is one merged to-do list built from all of them. The real cost was in the queue's own lookups, which are fixed.

What changed, in plain words

• Sign-in check: one database question instead of three, remembered for 30 seconds. Suspensions, bans, sign-outs and password changes still take effect on the next request. Roles changed by the staff-role script take up to 30 seconds (D-82).
• Red dots: a small "badges" call instead of downloading both lists every 30 seconds.
• Messages: one preview per thread instead of every message ever. Long threads and comment lists now show their newest lines; before, they showed the oldest and hid the newest.
• Review queue: built in a fixed handful of questions instead of several per item. A test proves it shows exactly what it showed before, for every kind of item.
• Indexes: ten added, so the slow lookups stop reading whole tables as they grow.
• Video server switch: one setting moves video work to a small server of its own; off by default (D-84, deploy/README.md "A small server for video").
• Picture check: the connector the documents promised now exists, with an Amazon Rekognition version, switched off. When on, it never decides; it tells the reviewer what it saw and puts flagged pictures first (D-83). Turn on only after the AWS AI-services opt-out is set.
• Other connectors: speech-to-text, video conversion and the guardian adult check are handed in at startup like storage and email, so each can be swapped or faked. The delivery-network purge now has a Cloudflare version beside CloudFront.
• Shared types: the web app now uses the API's contracts directly through a synced copy, and CI fails if the copy drifts. The switch found three fields the API sent but never declared; they are declared now.
• Clean-up: five never-used tables and one dead column removed (D-85). The migration refuses to run if any of those tables holds data.

Tests added

• load-budget: the exact database cost of every hot endpoint, with a budget each, plus concurrent bursts (600 tabs, 200 feed opens, 120 posts during reads).
• phase-a-regressions, phase-b-regressions, phase-c-seams, seams: that nothing a person sees changed, and that each connector works with a fake.
• e2e/performance.spec.ts (Playwright): page times, tap times, freezes, what an idle tab asks for, and that a flagged picture's finding is on screen without scrolling.

Final runs: API 700 of 700, browser 145 of 145.

Before deploying

• Migrations 0031 to 0034 run on deploy. 0031 to 0033 only add things. 0034 removes the unused tables and column; take the RDS snapshot first, as the deploy script already asks.
• Nothing needs turning on. The picture check, Cloudflare purge and video server are all off until their settings are set.

Sources

Files examined on dev/pilot:

• API: src/config.ts, src/context.ts, src/index.ts, src/server.ts, src/db/client.ts, all ten src/db/schema/*.ts, drizzle/meta/0030_snapshot.json, src/lib/{storage,cdn,mailer,transcriber,locks,posting-limit,phash,auth-plugin,authorize,gate}.ts, src/jobs/{boss,workers}.ts, every file under src/modules/, test/helpers/mem-storage.ts, the integration test context setups, scripts/deploy.sh, packages/contracts/src/.
• Web: src/lib/api.ts, src/lib/query-client.ts, every src/lib/*.ts hook module, src/api/schemas.ts, the layout, moderation, messaging and composer components, router.tsx, vite.config.ts, playwright.config.ts.
• Documents: docs/04-thnkrr-architecture.md §11, docs/07-decision-log.md, docs/18-aws-services-and-costs.md, docs/19-aws-why-and-alternatives.md, docs/25-public-profiles-and-search.md §6, docs/27-aws-deployment-decisions.md, notes/PROVIDER-SWAP-RESEARCH-2026-10-09.md, notes/PROVIDER-SWAP-PLAN-2026-10-09.md, notes/PRODUCTION-PLAN-2026-10-09.md, notes/MODERATION-PLAN-2026-10-05.md.
• Bedrock price for gpt-oss-safeguard-20b ($0.07 per million input tokens, $0.20 output) from the provider-swap research of 9 October 2026.