Louisville Voice Multilingual English Speaking Practice PWA for ESL Learners

Louisville Voice — Multilingual English Speaking Practice PWA #

Louisville Voice is a Progressive Web App that helps immigrants and refugees in Louisville Metro, Kentucky practice speaking English between their ESL classes. A learner watches a short video of an everyday situation — getting a bus pass, making a dentist appointment, walking in for a haircut — and then practices that same situation out loud with a voice coach that speaks their language when they get stuck. Three levels per situation, each unlocked by demonstrated mastery rather than by time spent.

The product collects no personal information at all. A learner unlocks it with an anonymous seat code handed out by a government office or a community partner, and the funding model runs on per-seat licensing to those partners rather than on anything extracted from the learner. The thirteen supported languages are Spanish, Pashto, Telugu, Haitian Creole, Kinyarwanda, Swahili, Arabic, French, Nepali, Somali, Turkish, Vietnamese, and Mandarin Chinese, plus English as the language of instruction.

This document specifies that product completely: its data model, its APIs, its voice pipeline, its scoring mathematics, its twelve launch modules, its administrative tools, its security and privacy posture, its infrastructure, and the order in which to build it. Every decision is made. An engineering team or an autonomous coding agent can begin at Section 34 and work to launch without needing information from any other source.

Table of Contents #

1. Before You Start — Customization Decisions
2. Project Overview and Vision
3. Scope, Non-Goals, and Success Criteria
4. Users, Roles, and Permissions
5. Technology Stack and System Architecture
6. Engineering Conventions and Standards
7. Data Model and Database Schema
8. Seat Provisioning, Identity, and Anonymous Sessions
9. Internationalization and Localization
10. Language Support Tiering and Speech Vendor Strategy
11. Content Model: Modules, Levels, Scenarios, and Assets
12. The Twelve Launch Modules — Full Content Specification
13. Video Asset Requirements and Production Handoff
14. Voice Practice Agent — Conversation Design
15. Voice Practice Agent — Runtime Pipeline and Transport
16. AI Safety, Guardrails, and Prompt-Injection Defense
17. Scoring and Mastery Engine
18. Progression, Badges, and Celebrations
19. Learner PWA — Information Architecture and Screens
20. Design System and Visual Language
21. Voice, Tone, and the English Source String Library
22. Accessibility and Low-Literacy Design
23. PWA Shell, Performance, and Low-End Device Budget
24. Learner API Specification
25. Admin API Specification
26. Partner Administration Dashboard
27. Content Management System
28. Analytics, Telemetry, and Privacy-Preserving Metrics
29. Security, Privacy, and Compliance
30. Infrastructure, Environments, and Deployment
31. Observability, Cost Control, and Vendor Budgets
32. Testing Strategy and Quality Assurance
33. Milestones and Execution Plan
34. Executor Instructions and Appendices

1. Before You Start — Customization Decisions #

This document specifies a complete, buildable system. Every decision required to build it has already been made and written down. Nothing in this document waits on an answer from anyone.

That said, an executing team or a funding partner may reasonably want a different answer to some of those decisions before the first line of code is written. This section exists so that those changes are made once, deliberately, at the start, rather than discovered as contradictions in month three.

1.1 How to use this section #

1. Read the decision table in Section 1.3 top to bottom.
2. For each row, either accept the default or write down the replacement value.
3. For every row you changed, open every section listed in the "Sections to edit" column and make the change consistently. Do not leave a changed decision recorded only in this section.
4. Record the final set of answers in the deployment configuration described in Section 30.2, so that infrastructure and application configuration agree with the document.

Every default in Section 1.3 is a real, working, self-consistent decision. If the executing team changes nothing, the system described in Sections 2 through 34 can be built, deployed, and operated without a single further input from the customer, the funder, or the product owner.

1.2 Rules for changing a decision safely #

1.3 The decision table #

1.4 If you change nothing, this is what you get #

A Progressive Web App at app.louisvillevoice.org that a learner opens on an inexpensive Android phone, installs to the home screen, and unlocks by typing a twelve-character code printed on a card their caseworker handed them. No name, no email, no password, no phone number. The app speaks fourteen languages, lays out correctly right-to-left in Arabic and Pashto, and holds twelve video scenarios drawn from real Louisville situations — a TARC service window, a JCPS enrollment office, a Circuit Court Clerk licensing counter, a community clinic exam room.

Each scenario opens into a voice practice session with an AI coach that listens, responds in character, and switches into the learner's own language when they get stuck. Each scenario has three levels; the learner advances by scoring 80 or better on at least their second attempt. Badges and short celebrations mark the wins. A private progress view, tied to nothing but the seat code, shows where they are.

Behind it: a Node.js and Fastify API, a dedicated WebSocket voice gateway, PostgreSQL and Redis on AWS in Ohio, Anthropic Claude for dialogue and scoring, Deepgram for listening, ElevenLabs for speaking, and Azure for pronunciation assessment — every speech vendor behind an interface so a language can be re-pointed by configuration.

Alongside it: a separate desktop admin application at admin.louisvillevoice.org where a handful of named staff at Louisville Metro and its partner agencies issue seat batches, print code sheets, watch activation and completion climb, and where content staff upload videos, write scenario scripts, manage translations, and publish modules without an engineer.

None of that requires another decision from anyone. The rest of this document specifies it.

2. Project Overview and Vision #

2.1 The problem, in the learner's words #

These are the statements the product is built to answer. They are written the way learners describe the problem, because the product is judged by whether it dissolves these sentences.

"In class I understand. On the bus I forget everything."

"I have class two nights a week. The other five nights, I speak my language at home. Then Monday I start again from the beginning."

"I am forty-three years old. I do not want to sound like a child in front of a young man at a counter."

"When I do not understand, I say yes. Then I have the wrong thing."

"My teacher is very kind. There are eighteen of us. I speak maybe four minutes."

"I do not want to give my name to a computer. I do not know where it goes."

"My daughter translates for me at the doctor. She is eleven. I do not want her to hear that."

2.2 The problem, in operational terms #

Community ESL programs in Louisville Metro are effective at what they are structured to do: grammar, literacy, vocabulary, and classroom comprehension. They are structurally incapable of delivering speaking volume. A typical community class runs two sessions a week, sixty to ninety minutes each, at a learner-to-instructor ratio between twelve and twenty-two to one. Even under generous assumptions about pair work, an individual learner produces on the order of four to eight minutes of spoken English per session — roughly ten to sixteen minutes a week.

Second-language speaking fluency is a production skill. It responds to volume of production under low anxiety, not to volume of instruction. Ten to sixteen minutes a week is below the threshold at which most adults consolidate spontaneous production, which is why learners report the pattern in Section 2.1: comprehension advances, production does not, and confidence decays between sessions.

The operational gap is therefore precise and narrow:

Two constraints make the gap harder than it first appears.

Constraint one: the phone. The device is frequently an Android handset three to six years old, 2 to 4 GB of RAM, on a metered prepaid plan, often shared within a household. The product must work there, not merely load there. Section 23 sets the performance and bundle budgets that make this binding rather than aspirational.

Constraint two: identity anxiety. A meaningful share of the target population will not create an account, and a meaningful share of those will not use a product that asks them to, regardless of what the privacy policy says. This is treated as a product constraint of the same hardness as the device constraint. Section 2.7 states why.

2.3 Who is served, and how many #

Planning assumption. This document plans against a Louisville Metro refugee resettlement volume of 1,500 to 2,500 people per year, arriving through the resettlement and community-services network that includes Kentucky Refugee Ministries, Catholic Charities of Louisville, the Kentucky Office for Refugees, and the Louisville Metro Office for Globalization. This is a stated planning assumption used to size the system, not a cited statistic. It should be replaced with the funder's own current figure before contracts are signed; doing so changes only the capacity numbers in Section 30.9 and the cost projections in Section 31.7, and changes nothing in the product design.

The planning assumption expands to the following sizing envelope, which is what the infrastructure, cost model, and rate limits are built against.

The three groups served.

1. Learners. Adults enrolled in, recently exited from, or waiting for a community ESL class in Louisville Metro. Predominantly first- through third-year arrivals. Literacy in the first language ranges from post-graduate to pre-literate; the product must be usable at the pre-literate end, which is why Section 22 treats icon-plus-audio navigation as a baseline rather than an accommodation. English level at entry ranges roughly from high beginner to low intermediate; below high beginner, the Level 1 guided mode is the entry point and is designed to be completable by repetition alone.

2. ESL program staff and community partner administrators. A small, named group at each partner agency — typically one to four people. They distribute seats, watch whether the seats they distributed are being used, and report to their own funders. They are not IT staff. The dashboard in Section 26 is designed for someone who opens it twice a week between appointments.

3. Louisville Metro office staff. A very small number of named people, principally in the Office for Globalization, who fund seats, allocate them to partner agencies, and need a Metro-wide view that no single partner can see. They hold the Platform Administrator role described in Section 4.5 or the Auditor role in Section 4.6.

Who is explicitly not served by this product. Children (the content is adult-situational and the product collects no parental consent, so it is not built or marketed for under-18 use); ESL instructors seeking classroom management tools (Section 3.3); and English speakers seeking to learn one of the thirteen support languages (the instruction direction is one-way into English).

2.4 What the product does #

Louisville Voice is an installable Progressive Web App that gives an immigrant or refugee in Louisville Metro unlimited, private, spoken English practice on the phone they already own, unlocked by a single anonymous code issued by a resettlement agency or a Metro office — no name, no email, no password, no account. The learner picks one of twelve short video scenarios drawn from errands they actually have to run in this city — buying a TARC bus pass, calling a dentist, enrolling a child at JCPS, picking up a prescription, sitting for a warehouse job interview — watches the situation play out, then steps into it and speaks. An AI voice coach plays the clerk, the receptionist, the interviewer; it listens, answers in character, and when the learner stalls it switches into their own language to explain, then switches back. Every module has three levels — guided repetition, open practice, and a real-world run with a complication — and the learner advances by scoring 80 or better on a level, with badges and a short celebration at each mastery. A private progress view tied to nothing but the seat code shows how far they have come, and a dashboard gives the agencies that funded the seats an aggregate, de-identified picture of whether the seats they paid for are being used.

2.5 What "good" looks like #

Targets in this subsection are directional statements of intent. The measurable, instrumented versions — with definitions, measurement methods, and owning sections — are in Section 3.5, which is canonical. Where the two appear to differ, Section 3.5 governs.

2.5.1 At six months after launch #

• Three partner agencies plus the Metro office have issued seats. At least 1,200 seats have been distributed and more than half have been redeemed.
• A weekly active learner completes two or more practice sessions a week and speaks for at least fifteen minutes a week inside the product — a measurable multiple of the classroom baseline in Section 2.2.
• At least one third of learners who redeem a seat master at least one module end to end, meaning all three levels at a Mastery Score of 80 or better.
• The voice loop feels like a conversation rather than a form: p95 from end-of-speech to first spoken response is at or under 1,800 milliseconds.
• Partner staff open their dashboard without being asked to, because it answers a question their own funder asks them.
• Zero learner personally identifying information exists anywhere in the system, and this is demonstrable by inspection of the schema in Section 7 rather than by assertion.
• No learner has been asked for a name, an email, a phone number, an address, a birth date, a photograph, or an immigration document.

2.5.2 At eighteen months after launch #

• Seat issuance is a routine line item in partner intake, handed out with the bus map and the clinic list rather than as a special program.
• More than 3,500 seats have been redeemed cumulatively, and weekly active seats exceed 1,200.
• Learners who master three or more modules show measurable gains in the pronunciation and fluency sub-scores defined in Section 17.4, tracked longitudinally per seat and reported in aggregate.
• The content set has grown beyond the twelve launch modules through the CMS in Section 27, with at least four modules authored, translated, and published without engineering involvement.
• At least one language has been promoted between voice tiers by configuration alone, per Section 10.4, proving the tiering system does what Section 1.3 row D16 and Section 10 claim.
• Cost per active seat per month is at or below $1.40, making the per-seat license defensible to a public funder against the alternative of paid instructor hours.
• The product is renewed by at least one funder who did not fund the pilot.

2.6 The funding model #

The product is free to every learner, permanently and without qualification. There is no learner payment path, no upgrade, no advertisement, no sponsored content, and no in-app purchase. Section 3.3 records the removal of these as deliberate non-goals rather than omissions.

Revenue comes from per-seat licensing sold to institutions: Louisville Metro government offices, resettlement agencies, community foundations, and grant-funded ESL programs. A funder buys a block of seats. The system issues that block as a batch of unique, printable codes. The funder's staff distribute the codes physically or by whatever channel they already use with clients. The funder sees activation and completion for their own seats, and nothing else.

The commercial argument the funder is being asked to accept is stated once, plainly: a seat costs a fraction of an hour of paid instructor time per month, and it delivers a multiple of the weekly speaking volume the funded classroom hour can deliver. The instrumentation in Section 28 exists in substantial part to let a funder verify that claim rather than take it on faith.

2.7 Why anonymity is a product requirement, not a compliance checkbox #

Most products treat privacy as a constraint applied after the fact: collect what is useful, then protect it, disclose it, and obtain consent for it. This product inverts that. The absence of identity is a functional feature of the product, and removing it would remove the product's primary mechanism of action.

The reasoning, stated so that no future decision reverses it by accident:

1. The target population includes people with acute immigration-status anxiety. Some are asylum seekers with pending cases. Some have mixed-status households. Some arrived from states where a government database is a mechanism of harm rather than a mechanism of service. For these people, a name field is not an inconvenience. It is a stop sign.

2. The people who most need speaking practice are the ones most likely to refuse a sign-up form. Willingness to hand over identity correlates inversely with the anxiety that also suppresses speaking practice. A registration wall does not merely reduce the funnel; it filters out precisely the learners the funder is paying to reach.

3. Speaking practice requires low anxiety to work at all. The mechanism of action in Section 2.2 is volume of production under low anxiety. A learner who believes their recorded voice is attached to their name and stored somewhere will speak less, hedge more, and abandon a turn rather than risk an error. Anonymity is therefore not a privacy posture layered over the learning design; it is a precondition of the learning design.

4. A promise the architecture cannot break is worth more than a policy. A caseworker can say "this app does not ask who you are" and be believed, because the app visibly never asks. That is a distribution advantage no privacy policy purchases. Section 7's schema is the proof: there is no column to put a name in.

5. Data that does not exist cannot be subpoenaed, breached, sold, or re-purposed by a future administration. The strongest control for learner data is the absence of learner data. Section 29.9 sets retention to zero for raw audio and to non-verbatim derived artifacts for transcripts, for this reason.

What this costs, stated honestly. Anonymity is not free, and the executing team should know the bill in advance:

Each of these is a real cost and each is accepted. The one deliberate exception: staff work email addresses for Content Editors, Partner Administrators, Platform Administrators, and Auditors. Staff are named, authenticated, and audited, because staff take actions with financial and content consequences. That exception applies to staff only and never to learners, and it is documented in Section 4.1 and Section 29.3 so that it can never be quietly widened.

2.8 Design principles #

These ten principles are the standing tie-breaker for every decision this document does not explicitly settle. Later sections are expected to be judged against them, and a reviewer is entitled to reject an implementation that violates one, citing the number.

2.9 What success would mean beyond the metrics #

The instrumented definition of success is Section 3.5. The human definition is this: a learner walks into a TARC customer service window, asks for a monthly pass, is asked a question they did not expect, and answers it — because they have already had that exact conversation eleven times on their phone, in private, where being wrong cost nothing.

Every requirement in this document is subordinate to that sentence.

3. Scope, Non-Goals, and Success Criteria #

3.1 In scope — the eleven core features #

The product contract is eleven features. Everything in this document exists to deliver one of them, to support one of them, or to operate them. A change request that does not map to one of these eleven rows is a scope change and follows Section 3.6.

Also in scope, as required supporting work. These are not features a user sees, and they are not optional. They are listed so that no plan treats them as discretionary.

3.2 Non-goals #

Each row is a thing this product deliberately does not do. The reason is given so that a future contributor can tell the difference between an omission and a decision. Reversing any of these is a scope change under Section 3.6, not a bug fix.

3.3 Deliberately deferred to v2 #

These are different from non-goals. A non-goal is refused on principle. A deferred item is wanted, is compatible with the design, and is out of the launch release for time, cost, or evidence reasons. Each row states the concrete trigger that promotes it into scope.

3.4 Scope boundary rules #

3.5 Success criteria #

This subsection is canonical for every target figure in this document. Where Section 2.5 or any other section states a target informally, this table governs.

Definitions used throughout:

• Issued seat — a seat row created as part of a batch, whether or not distributed.
• Redeemed (activated) seat — a seat whose code has been successfully exchanged for a session at least once.
• Active seat (weekly) — a redeemed seat with at least one practice session containing at least one scored spoken turn in the trailing seven days. A seat counts once no matter how many of its bound devices were used; the unit of measurement is the seat, never the device.
• Practice session — a continuous voice practice engagement on one level, from session open to session close or 15 minutes of inactivity, whichever comes first.
• Attempt — one complete run of a level producing a Mastery Score.
• Mastered level — an attempt with Mastery Score ≥ 80, with at least two attempts recorded at that level.
• Mastered module — all three levels mastered.

3.5.1 Reporting cadence and ownership #

3.5.2 Measurement integrity rules #

3.6 What would make this project a failure #

Success is a set of numbers. Failure is a set of conditions. Any one of the following means the project has failed at its purpose, regardless of what the metrics say.

4. Users, Roles, and Permissions #

4.1 The role model #

The system has exactly five roles. Four are required; the fifth, Auditor, is required in any deployment where a funder requests read-only oversight, and is specified here so that it never has to be invented under pressure.

Roles are singular and exclusive. A staff account holds exactly one role. There is no role stacking, no role inheritance hierarchy, and no per-user permission override. If a person needs two capability sets, they receive the role that contains both, or they receive a second account with a different work email. This is a deliberate simplification: the population of staff accounts is measured in dozens, and a flexible permission system would add a large authorization surface to protect a population small enough to enumerate by hand.

The staff-email exception. Work email addresses for the four staff roles are the only personal data in the system. This is a deliberate, narrow exception to the zero-PII rule, recorded in Section 2.7 and controlled in Section 29.3. It applies to staff, who take actions with financial and editorial consequences and must be individually accountable. It never applies to learners, and no implementation may extend it to learners under any justification.

Learner and staff identities never mix. The learner session and the staff session are issued by different endpoints, carried in different cookies on different hostnames, validated by different middleware, and stored in different tables. There is no code path by which a staff session can authenticate against a learner endpoint or the reverse, and Section 32.4 requires a test asserting this.

4.2 Learner #

Who they are. An adult immigrant or refugee in Louisville Metro who received a seat code from a resettlement agency, an ESL program, or a Metro office. They are described in detail in Section 2.3.

How they authenticate.

1. They open the app and select a language. No authentication is required to see the language picker or the welcome screen.
2. They enter their seat code. The client normalizes it — uppercase, dashes and whitespace stripped — validates the Crockford check symbol locally, and posts it to the redemption endpoint.
3. On success the server creates a seat session bound to the device, sets an opaque refresh token in an HttpOnly; Secure; SameSite=Lax cookie, and returns a short-lived access token held only in memory by the client.
4. On subsequent visits the client silently exchanges the refresh cookie for a new access token. The learner never sees the code again unless the session is revoked, the cookie is lost, or another device replaces this one on the seat.

The complete flow, including the seat-code format, the device-binding fingerprint, token lifetimes, rotation, replay detection, rate limiting, and every error condition, is canonical in Section 8.

Session lifetime. Access token 15 minutes. Refresh token 90 days from last use, sliding, rotated on every exchange. A seat itself does not expire once redeemed. A learner who opens the app at least once every 90 days never re-enters a code. There is no idle timeout inside the app; a learner may leave a practice screen open indefinitely, though the voice session itself closes after 15 minutes of silence per Section 15.11 and can be reopened with one tap.

What they can see. The language picker; the module library; scenario videos for published modules; practice sessions for unlocked levels; their own progress, scores, and badges; localized help content; the privacy statement.

What they can do. Redeem a seat; change language at any time; watch videos; start, pause, and end practice sessions; request hints and native-language help; retry any level any number of times; open their seat on a second device and replace the least recently used device once every device slot is full; request erasure of their seat's data.

What they explicitly cannot do.

Data erasure. A learner may erase their seat's data from the app without contacting anyone. The erasure path deletes progression, attempts, scores, badges, and sessions for that seat, marks the seat as erased and non-redeemable, and is irreversible. It is the only hard-delete path that touches learner progress, and it is specified in Section 29.10. Because no identity exists, erasure requires only possession of the active session — the same standard as every other learner action.

4.3 Content Editor #

Who they are. Two to five members of the content team: an instructional designer, one or two scenario writers, and a translation coordinator. They write and maintain the twelve launch modules and everything that follows. They are not engineers and must never need one to ship content.

How they authenticate. Work email plus password (Argon2id, parameters in Section 29.3) plus mandatory TOTP. Accounts are created by invitation only, per Section 4.11. There is no self-service registration on any admin hostname.

Session lifetime. Access token 30 minutes, sliding. Absolute session maximum 12 hours, after which full re-authentication including TOTP is required. Idle timeout 60 minutes with a warning at 55 minutes and a one-click extension. Re-authentication with TOTP is additionally required for publishing a module version and for rolling back a published version — the two irreversible-in- effect actions this role holds.

What they can see. All modules in all states — draft, in review, published, archived. All scenario scripts, dialogue configuration, required information items, hint ladders, and glossaries. All English source strings. All translations in all fourteen locales, with their coverage and review status. The badge catalogue. All video assets and their processing status. The content audit log.

They cannot see any partner, any seat, any batch, any activation figure, any completion figure, or any dashboard. Content work does not require knowing who funded a seat, and separating these concerns keeps a content compromise away from partner data.

What they can do. Create, edit, duplicate, and archive modules; configure the three levels of each module including required information items, curveballs, personas, and hint ladders; upload scenario videos and monitor transcoding; author and edit English source strings; import, edit, and approve translations for all fourteen locales; author caption files; manage badge definitions and unlock rules; preview any module at any level exactly as a learner would experience it; publish and roll back module versions.

What they explicitly cannot do.

4.4 Partner Administrator #

Who they are. One to four named staff at each partner organization — a resettlement agency caseworker supervisor, an ESL program coordinator, a Metro office program manager. They distribute seats and answer to their own funder about whether those seats were used. They are not technical users. The dashboard in Section 26 assumes someone who opens it for five minutes, twice a week, between client appointments.

How they authenticate. Work email plus password plus mandatory TOTP, by invitation only, from a Platform Administrator or from another Partner Administrator within the same partner organization. The invitation flow is Section 4.11.

Session lifetime. Access token 30 minutes, sliding. Absolute maximum 12 hours. Idle timeout 30 minutes — shorter than the Content Editor because these sessions are frequently opened on shared office workstations. TOTP step-up re-authentication is required for: issuing a seat batch, revoking a seat or a batch, and exporting a CSV.

What they can see. Only their own partner organization, always. Specifically: their partner profile; every seat batch their organization has issued, with issued, redeemed, active, and expired counts; seat-level status (issued, redeemed, active, revoked, expired, erased) identified by seat code and by nothing else; aggregate module completion, level distribution, and badges earned for their own seats; weekly activity trends for their own seats; their organization's staff list; their own partner's audit log.

What they can do. Issue seat batches within their organization's remaining allocation; generate and download printable code sheets; revoke an individual seat or an entire batch; reissue a seat to replace a lost code; label and annotate batches; export aggregate CSV for their own partner; invite and deactivate staff within their own partner organization at Partner Administrator or Auditor level; reset another staff member's TOTP within their own organization; view their own partner's audit log.

What they explicitly cannot do.

4.5 Platform Administrator #

Who they are. Two to four people: the technical operations owner and one or two Metro program leads. This is the smallest role and the most privileged. Every action it takes is audited.

How they authenticate. Work email plus password plus mandatory TOTP, by invitation from an existing Platform Administrator only. There must be at least two active Platform Administrator accounts at all times; the system refuses to deactivate the last one, returning LAST_PLATFORM_ADMIN.

Session lifetime. Access token 15 minutes, sliding — shorter than other staff roles. Absolute maximum 8 hours. Idle timeout 20 minutes. TOTP step-up re-authentication is required for: creating or modifying a partner, changing a seat allocation, changing any role assignment, resetting another account's TOTP, deactivating a staff account, changing the mastery threshold or scoring configuration, and toggling any feature flag in the production environment.

What they can see. Everything the other roles can see, plus: all partners; Metro-wide roll-ups across every partner; the full platform audit log; the vendor cost and usage dashboard; feature flag state; system health and SLO dashboards; per-module usage aggregates across all partners.

They still cannot see individual learner speech, transcripts, or turn-level history, because those do not exist. Privilege does not create data.

What they can do. All Content Editor capabilities; all Partner Administrator capabilities across every partner; create and configure partner organizations and their seat allocations; invite, reassign, and deactivate any staff account in any role; reset any account's TOTP; manage feature flags; change the mastery threshold and scoring configuration; read the platform-wide audit log; export platform-wide aggregate data; trigger administrative jobs such as batch expiry recomputation.

What they explicitly cannot do.

4.6 Auditor #

Who they are. Zero to three people: a funder's program officer, a grant compliance reviewer, or an internal oversight role. The role exists so that oversight never requires handing someone a Partner Administrator or Platform Administrator account.

How they authenticate. Identical to other staff roles: work email plus password plus mandatory TOTP, by invitation from a Platform Administrator. An Auditor account is created with a scope of either exactly one partner or all partners; the scope is fixed at invitation and can be changed only by a Platform Administrator, which is an audited action.

Session lifetime. Access token 30 minutes, sliding. Absolute maximum 8 hours. Idle timeout 30 minutes. No step-up re-authentication is required, because the role holds no write capability.

What they can see. Read-only access to exactly what a Partner Administrator sees for their scoped partner, or what a Platform Administrator sees in aggregate if scoped Metro-wide: seat batch counts, activation, completion, level distribution, badges earned, activity trends, and the audit log for their scope. They may also see the published content catalogue — module titles, levels, and published state — because a funder legitimately asks what was delivered.

What they can do. View and export aggregate CSV within their scope. That is the complete list of capabilities.

What they explicitly cannot do. Every write operation in the system, without exception: no seat issuance, no revocation, no reissue, no content creation or editing, no publishing, no staff administration, no configuration change, no flag change. Write attempts fail with INSUFFICIENT_ROLE at the authorization middleware before reaching any handler. They also cannot see individual learner data of any kind, on the same terms as every other role.

4.7 Permission matrix #

Legend: A = Allow. D = Deny. Cn = Conditional, where the condition is defined in Section 4.7.1. A blank cell never appears; every capability has an explicit value for every role.

Enforcement is server-side in all cases. The admin client hides controls the caller cannot use, but hiding is a usability affordance and never a control; every capability below is checked in the authorization middleware described in Section 25.3 and, where scope applies, again in the query layer described in Section 4.9.

4.7.1 Conditions #

4.7.2 Invariants that no condition may relax #

4.8 How role assignment works #

A role is a column, not a set. Each staff account row carries exactly one role value from a PostgreSQL native enum, and exactly one partner_id foreign key that is nullable. The combination of the two is the complete authorization state of a staff account.

These pairings are enforced by a check constraint on the staff table, so an inconsistent state cannot exist even if application logic is bypassed. The constraint is authored in Section 7, which owns the schema; the rule it encodes is stated here because it is an authorization rule.

-- Illustrative form of the constraint owned by Section 7.
ALTER TABLE staff_accounts
  ADD CONSTRAINT ck_staff_accounts_role_scope CHECK (
    (role = 'content_editor'  AND partner_id IS NULL)
    OR (role = 'partner_admin'   AND partner_id IS NOT NULL)
    OR (role = 'platform_admin'  AND partner_id IS NULL)
    OR (role = 'auditor')
  );

Assignment rules.

Authorization is evaluated per request, never cached in the token. The access token carries the account identifier and a token version, not the role. The role and partner scope are loaded from the datastore on every request through a request-scoped cache with a maximum lifetime of five seconds. This costs one indexed primary-key lookup per request and makes role changes take effect almost immediately, which is what Section 4.10 requires.

4.9 How partner scope is enforced in the query layer #

Partner scoping is the single most important authorization control in the admin system, because almost every failure mode of a multi-tenant dashboard is one query that forgot its tenant filter. The design assumption is therefore that a handler will eventually forget, and the system is built so that forgetting fails closed and loudly.

There are four layers. All four are required; none is a substitute for another.

4.9.1 Layer 1 — the authorization context #

Every authenticated admin request constructs exactly one AuthContext in middleware. Handlers receive it and never reconstruct it, never read the role from a header, and never take a partnerId from the request body or the query string for scoping purposes.

/** Constructed once per request by the admin auth middleware. Immutable. */
export type AuthContext = Readonly<{
  staffId: string;                  // UUIDv7
  role: 'content_editor' | 'partner_admin' | 'platform_admin' | 'auditor';
  /** The caller's partner scope. null means "all partners". */
  partnerId: string | null;
  /** True when the caller may read across every partner. */
  isPlatformScoped: boolean;        // role === 'platform_admin' || (role === 'auditor' && partnerId === null)
  /** True when the caller holds no write capability at all. */
  isReadOnly: boolean;              // role === 'auditor'
  requestId: string;                // ULID, echoed in meta.requestId
}>;

4.9.2 Layer 2 — the scoped repository #

No admin handler may build a query against a partner-scoped table directly. All access goes through repository functions that take the AuthContext as their first argument and apply the filter themselves. The filter is applied in exactly one place per table.

import { and, eq, isNull, sql } from 'drizzle-orm';

/** Tables that carry a partner_id and must always be scoped. */
const PARTNER_SCOPED_TABLES = [
  'partners', 'seat_batches', 'seats', 'staff_accounts',
  'audit_log_entries', 'aggregate_daily_partner_metrics',
] as const;

/**
 * The one and only place a partner filter is expressed.
 * Platform-scoped callers receive an always-true predicate.
 */
function partnerScope(ctx: AuthContext, column: PgColumn) {
  if (ctx.isPlatformScoped) return sql`true`;
  if (ctx.partnerId === null) {
    // A non-platform-scoped caller with no partner is a bug, not an empty filter.
    throw new ScopeConfigurationError(ctx.staffId, ctx.role);
  }
  return eq(column, ctx.partnerId);
}

export async function listSeatBatches(
  ctx: AuthContext,
  params: { limit: number; cursor: string | null },
) {
  return db
    .select()
    .from(seatBatches)
    .where(and(
      partnerScope(ctx, seatBatches.partnerId),
      isNull(seatBatches.deletedAt),
      cursorPredicate(seatBatches.id, params.cursor),
    ))
    .orderBy(seatBatches.id)
    .limit(params.limit + 1);
}

A caller who is not platform-scoped and has no partnerId throws rather than returning an unfiltered result set. Failing closed on a misconfiguration is mandatory; returning everything is the failure this whole subsection exists to prevent.

4.9.3 Layer 3 — PostgreSQL row-level security as the backstop #

The application connects with a database role that has row-level security enforced on every partner-scoped table. At the start of each request the connection sets two transaction-local settings, and the policies read them. If a query somehow escapes the repository layer, the database still filters it.

-- Enabled on every partner-scoped table. Illustrative; Section 7 owns the DDL.
ALTER TABLE seat_batches ENABLE ROW LEVEL SECURITY;
ALTER TABLE seat_batches FORCE ROW LEVEL SECURITY;

CREATE POLICY rls_seat_batches_partner_scope ON seat_batches
  USING (
    current_setting('app.is_platform_scoped', true) = 'on'
    OR partner_id = nullif(current_setting('app.partner_id', true), '')::uuid
  );

/** Applied to the pooled connection at the start of every admin request transaction. */
await tx.execute(sql`
  SELECT set_config('app.partner_id', ${ctx.partnerId ?? ''}, true),
         set_config('app.is_platform_scoped', ${ctx.isPlatformScoped ? 'on' : 'off'}, true)
`);

Both settings are transaction-local (set_config(..., true)), so they cannot leak between requests sharing a pooled connection. A connection that is returned to the pool mid-transaction is destroyed rather than reused, per the pool configuration in Section 5.3.

4.9.4 Layer 4 — the static and dynamic guards #

4.9.5 The not-found rule #

A record that exists but belongs to another partner returns HTTP 404 with error code NOT_FOUND. It never returns 403. Returning 403 would confirm the record exists, which lets one partner enumerate another partner's batch identifiers. FORBIDDEN is used only when the record is inside the caller's scope but the caller's role may not perform the action — for example an Auditor attempting to revoke a seat in their own partner.

4.9.6 Aggregate queries #

Aggregates are precomputed per partner per day by the job described in Section 28.7, into a partner-scoped table. The dashboard reads the precomputed rows through the same scoped repository, so an aggregate cannot accidentally span partners. A Metro-wide roll-up is a separate query that sums the same rows and is callable only when ctx.isPlatformScoped is true; the repository function for it takes the context and throws ScopeViolationError if it is not.

Small-cell suppression applies to every aggregate before it leaves the server, per Section 28.6. A Partner Administrator with three redeemed seats sees suppressed cells rather than numbers that would describe three identifiable individuals.

4.10 What happens on a role change mid-session #

Because authorization is evaluated per request from the datastore rather than read from the token, a role or scope change takes effect within the five-second request-scoped cache window. The following behavior is required in addition.

In-flight requests. A request that is already executing when the change lands completes under the authorization it started with. The window is bounded by the request timeout of 30 seconds in Section 5.7. Requests that mutate data write an audit entry recording the role in effect at the time the request began, so the audit log is never retroactively inconsistent.

Learner sessions are unaffected by staff role changes. The only events that invalidate a learner session are seat revocation, seat erasure, replacement of that device's binding, a seat transfer, and refresh-token reuse detection, all of which are specified in Section 8.

4.11 Staff invitation flow #

There is no self-service registration on any admin hostname. Every staff account begins as an invitation issued by an authorized human.

Preconditions. The inviter holds platform_admin (any role, any partner) or partner_admin (only partner_admin or auditor, only within their own partner, condition C13). The inviter has completed a TOTP step-up within the last 10 minutes.

Steps.

1. The inviter opens Staff, selects Invite, and provides: work email address, display name, role, and — when the inviter is a Platform Administrator inviting a partner_admin or a scoped auditor — the partner organization.
2. The server validates: the email is syntactically valid and its domain is not a known disposable-mail domain; no active or pending account exists with that email; the requested role and partner combination satisfies the constraint in Section 4.8; the inviter is permitted to invite that role at that scope. Failures return EMAIL_ALREADY_INVITED, EMAIL_IN_USE, INVALID_ROLE_SCOPE, or INSUFFICIENT_ROLE.
3. The server creates a staff account row in pending_invitation status with the role and partner set, no password hash, and no TOTP secret. It generates a 32-byte random invitation token, stores only its SHA-256 hash with a 7-day expiry, and writes an audit entry.
4. An invitation email is sent to the work address containing a single-use link. The email states the inviter's name, the organization, the role, and the expiry. It contains no password and no code.
5. The invitee opens the link. The server validates the token hash, that it is unexpired, unused, and that the account is still pending_invitation. An invalid or expired token renders a generic "this invitation is no longer valid" screen with a request-a-new-invitation instruction, and does not disclose whether the email is known.
6. The invitee sets a password. Requirements: minimum 12 characters, checked against a breached- password corpus, no maximum length below 128, no composition rules, no forced rotation. Hashing is Argon2id with the parameters in Section 29.3.
7. The invitee enrolls TOTP. The server generates a secret, renders a QR code and the secret in text form for manual entry, and requires one valid six-digit code before enrollment completes. Enrollment is mandatory and cannot be skipped, postponed, or dismissed.
8. The server issues ten single-use recovery codes, displays them once, and requires an explicit acknowledgment that they have been saved. Only Argon2id hashes of the codes are stored.
9. The account moves to active. The invitation token hash is deleted. An audit entry records the acceptance, the account identifier, the role, and the partner.
10. The invitee is signed in and lands on the default screen for their role: Content Editor lands on the module list; Partner Administrator lands on their partner's overview; Platform Administrator lands on the Metro-wide overview; Auditor lands on the overview for their scope.

Invitation edge cases.

4.12 Staff offboarding flow #

Offboarding is deactivation, never deletion. The staff row is retained with deleted_at set, because the audit log references it and an audit trail that points at a missing actor is not an audit trail.

Preconditions. The actor holds platform_admin (any account except the last active Platform Administrator and except their own account) or partner_admin (only partner_admin and auditor accounts within their own partner). A TOTP step-up within the last 10 minutes is required.

Steps.

1. The actor opens Staff, selects the account, and chooses Deactivate. The interface states in plain language what deactivation does and that it cannot be undone by re-enabling the same row.
2. The server validates that the target is not the last active platform_admin (LAST_PLATFORM_ADMIN) and not the actor's own account (CANNOT_DEACTIVATE_SELF), and that the actor's scope permits it (INSUFFICIENT_ROLE).
3. In a single transaction the server: sets deleted_at and status deactivated; increments token_version, which invalidates every access token; deletes every refresh token row for the account; deletes the TOTP secret and all unused recovery-code hashes; nulls the password hash; and writes an audit entry naming the actor, the target, the target's role and partner, and the reason text if supplied.
4. Any in-flight request from the target completes under its existing authorization and then fails at its next request with 401 ACCOUNT_DEACTIVATED.
5. Content the target authored is unaffected. Modules, translations, and published versions remain attributed to the account identifier, and the audit log still resolves the display name, because the row still exists.
6. Seat batches the target issued are unaffected. Batches belong to the partner organization, not to the individual who created them, and remain fully manageable by that partner's remaining staff.
7. A notification email is sent to every other active administrator in the same scope — the partner's remaining Partner Administrators, or all Platform Administrators when the target was platform- scoped — stating who was deactivated, by whom, and when.
8. If the deactivated account was the partner's only Partner Administrator, the interface warns the actor before confirming and the resulting notification is escalated to all Platform Administrators, because that partner can no longer issue seats until a new administrator is invited.

Reinstatement. A deactivated account is never reactivated. If the same person returns, a Platform Administrator issues a fresh invitation, which creates a new account row with a new identifier. The old row remains as an audit anchor. This guarantees that a period of separation is always visible in the record rather than hidden behind a toggled flag.

Automatic deactivation. An active staff account that has not authenticated in 180 consecutive days is automatically deactivated by a nightly job, following the same transaction as step 3 with the actor recorded as the system. A warning email is sent at 150 and 173 days. Platform Administrator accounts are exempt from automatic deactivation only when doing so would leave fewer than two active Platform Administrators.

Offboarding edge cases.

4.13 User journeys #

These journeys are normative. They define the sequence a correct implementation must produce, and each is directly testable against the end-to-end suite in Section 32.4. Where a step depends on behavior owned by another section, the section is cited and the behavior is not restated.

4.13.1 Journey J1 — A learner's first ten minutes #

Actor. Amina, 34, arrived eight months ago, attends a community ESL class two evenings a week, speaks Pashto, reads Pashto slowly, reads no English. Device: a four-year-old Android phone, 3 GB RAM, Chrome, prepaid data. She was handed a card by her caseworker at Kentucky Refugee Ministries with a web address and a twelve-character code.

Target. From opening the link to her first scored spoken turn in under six minutes (metric M14 in Section 3.5).

1. She types the address into Chrome. The service worker is not yet installed, so this is a cold first load. The initial payload is within the low-end budget in Section 23.6 and the first meaningful paint is under 2.5 seconds on a simulated 3G profile.
2. The first screen is the language picker, and nothing else. There is no logo animation, no marketing copy, no cookie banner, and no consent dialog, because nothing is collected that would require one. The screen shows fourteen options, each rendered in its own language and script — پښتو for Pashto, not "Pashto" — because a learner who reads no English cannot find their language in an English list.
3. She taps پښتو. The interface immediately re-renders right-to-left. Layout direction comes from CSS logical properties, so no second stylesheet loads and no visible reflow occurs. The Pashto translation bundle is fetched and cached by the service worker (Section 9.5). Her choice is persisted to local storage, keyed per device, and will be reapplied on every future visit before first paint.
4. The welcome screen appears in Pashto. It contains one sentence explaining what the app is, a speaker icon that reads that sentence aloud in Pashto, and one primary button: enter your code. The button is in the bottom third of the viewport, reachable with her thumb (principle P4).
5. She taps the speaker icon and listens. The audio is a pre-generated Pashto voice file shipped with the locale bundle, not a runtime synthesis call, so it plays instantly and costs nothing.
6. She taps the primary button. The code entry screen appears: one large input with a numeric-and- uppercase soft keyboard hint, the expected format shown as a visual mask XXXX-XXXX-XXXX, a photograph-style illustration of the physical card so she can see what she is looking for, and a speaker icon reading the instruction aloud in Pashto.
7. She types the code from the card in lowercase and without dashes. The client uppercases it, inserts the dashes visually as she types, and ignores whitespace. Crockford Base32 substitution is applied on input, so a typed O becomes 0 and a typed I or l becomes 1, which removes the most common transcription errors before they reach the server.
8. The check symbol validates locally. If it had failed, the screen would show, in Pashto, "that code is not quite right — please check it again," with the illustration highlighting the code's position on the card. It would not say "invalid", would not use red, and would not clear what she typed (principle P2).
9. She taps Continue. The client posts the normalized code to the redemption endpoint. The button enters a loading state and remains disabled until the response resolves, so a double tap cannot produce two redemptions.
10. The server validates the code, finds the seat in issued status, marks it redeemed, binds it to this device, records the redemption timestamp, and returns a session. The full flow, the device-binding inputs, and every failure code are canonical in Section 8.
11. She lands on the module library. Twelve cards, each with a still frame from its video, a title in Pashto, and a progress indicator showing three level pips, all empty. Nothing is locked at the module level; every module is open from the start. Only levels within a module are gated.
12. An install prompt appears as a dismissible bottom sheet, not a browser-native banner, explaining in Pashto that she can add the app to her home screen. It appears once, is dismissible with one tap, and does not reappear for 14 days if dismissed (Section 23.4). She taps Add.
13. She taps the first card, bus-pass — Getting a Bus Pass, set at a TARC customer service window.
14. The module screen shows the scenario video with a large play control. Below it, three level rows: Guided (open), Practice (locked), Real World (locked). Locked rows show a lock icon and, in Pashto, "finish Guided first" — never a bare disabled control with no explanation (principle P10).
15. She plays the video. It is 70 seconds. HLS adaptive streaming starts at the lowest rendition and steps up; the first frame renders within 1.5 seconds. Pashto captions are on by default because her interface language is a support language, and they are burned into the player's caption track rather than the video itself, so she can turn them off.
16. The video ends. A single primary button appears: start practice, Guided level. There is no quiz, no comprehension check, and no intermediate screen.
17. She taps it. The microphone permission prompt appears — the browser's own, triggered by her tap, never on page load. The screen behind it explains in Pashto, with a microphone illustration, why the permission is needed and that nothing is recorded or kept.
18. She grants permission. If she had denied it, the app would show a Pashto explanation with device-specific instructions for re-enabling it and would keep the video and progress screens fully usable rather than blocking the app (principle P10).
19. The practice screen loads: the scenario still frame at the top, a large central microphone control, a visible audio level meter driven by an AudioWorklet so she can see the app is hearing her, and a persistent help control in her language.
20. The WebSocket connects to the voice gateway. The connection handshake, authentication, and protocol are canonical in Section 15.
21. The bot speaks first, in English, in role as a TARC clerk: a short greeting and a simple question. Level 1 guided opens by offering the phrase, so immediately after the question the bot supplies the line she can say back. Pashto is Tier B, so she receives spoken help in Pashto through TTS while her Pashto input is treated as a hint request rather than scored speech (Section 10.2).
22. Text appears alongside the audio: the English line in large type, and beneath it the Pashto translation in smaller type. Both are visible simultaneously at Level 1. Section 14.5 governs what is shown at each level.
23. She says nothing for six seconds. The bot does not fail her, does not restart, and does not time out. It waits, then offers the phrase again more slowly. This is the silence ladder in Section 14.6 and it is required behavior, not a fallback (principle P3).
24. She speaks. The level meter moves. Her audio streams to the gateway in 20-millisecond Opus frames. Nothing is written to disk at any point (Section 29.9).
25. End of speech is detected. The turn is transcribed, scored, and the bot's response is generated and synthesized. The first byte of spoken response reaches her device inside the p95 budget of 1,800 milliseconds (metric M6). To her, the pause is short enough to read as a person thinking.
26. The bot responds in role and moves the scenario forward. A small, non-intrusive positive marker appears next to her turn. No score number is shown mid-session; scores appear at the end of the attempt (Section 17.8).
27. Turn four confuses her. She taps the help control. A sheet slides up offering three options in Pashto, each with an icon: say it again slowly, explain in Pashto, or show me the words. She taps explain in Pashto. The bot switches language, explains the situation in Pashto through TTS, and returns to English in role without losing the scenario state (Section 14.7).
28. Turn six, she says something off-scenario — she asks, in Pashto, whether the bus is free for people with her visa status. The bot does not answer. It acknowledges the question warmly, states in Pashto that it can only practice the conversation and that her caseworker can answer that, and returns to the scenario. This is the refusal-and-redirect behavior in Section 16.5 and it is mandatory (non-goal NG15).
29. The scenario completes at turn nine. The session closes cleanly and the WebSocket disconnects.
30. The results screen appears: a Mastery Score of 71 out of 100, presented as a progress arc filling toward 80 rather than as a grade. Beneath it, in Pashto, two specific, concrete things that went well and one thing to try next time — never a list of errors (principle P2).
31. Because 71 is below 80, the Practice level stays locked. The screen does not say "failed". It says, in Pashto, "you need 80 to open the next level — try again," with a large try-again button as the primary action. Section 21.3 owns the exact wording standard.
32. She taps try again. The second attempt starts immediately, with no video replay required and no loading screen, because the module assets are already warm.
33. She scores 84. The threshold is met and this is her second recorded attempt at the level, so the two-attempt minimum is satisfied and Practice unlocks.
34. A celebration plays: a short animation, a badge — "First Steps", her first level completed — and an optional sound. The animation honors prefers-reduced-motion and degrades to a static state change (Section 18.6). Total duration is under 2.5 seconds and it is dismissible with a tap.
35. The module screen returns with the Guided row marked complete and the Practice row unlocked.
36. She taps her progress view: one module started, one level mastered, one badge, eleven minutes of practice time. It is hers alone; no staff account anywhere can see any part of it (principle P9, matrix row 10).

Elapsed to first scored turn: approximately four minutes. Personal data collected: none. Account created: none. Audio retained: none.

Failure branches from J1.

4.13.2 Journey J2 — A Metro staffer issues 200 seats to Kentucky Refugee Ministries #

Actor. David, program manager at the Louisville Metro Office for Globalization, holding platform_admin. Kentucky Refugee Ministries already exists as a partner organization with a seat allocation of 1,000, of which 640 remain unissued.

1. David opens the admin application and signs in with email, password, and a TOTP code. He lands on the Metro-wide overview, because his role is platform-scoped.
2. He opens Partners and selects Kentucky Refugee Ministries. The partner page shows the allocation of 1,000, 360 seats issued across three prior batches, and the current activation rate for each.
3. He selects Issue Seats. The form requires: quantity, a batch label, and a distribution note. It displays the remaining allocation, 640, next to the quantity field.
4. He enters 200, labels the batch "KRM Fall Intake 2026", and notes "Distributed at intake appointments, Preston Highway office." Labels and notes are free text limited to 120 and 500 characters and are visible to that partner's staff and to Platform Administrators.
5. He submits. The server re-validates the remaining allocation inside the transaction; had another administrator issued seats in the interim, the request would fail with ALLOCATION_EXCEEDED rather than overdrawing.
6. Because seat issuance is a step-up action, he is prompted for a fresh TOTP code. He enters it.
7. In one transaction the server creates the batch row, generates 200 seat codes, stores a salted hash and a four-character display prefix for each, sets each seat to issued with an expiry 365 days out, and writes an audit entry naming him, the partner, the batch, and the quantity. Code generation, collision handling, and the storage model are canonical in Section 8.4.
8. The plaintext codes are written once to a short-lived encrypted object with a 72-hour lifecycle rule. This is the only place the plaintext ever exists after generation. No one — including David and including any Platform Administrator — can retrieve a plaintext code after that window (matrix row 49).
9. The batch page appears with a prominent notice: the code sheet is available for 72 hours and cannot be regenerated afterward. The notice states the exact expiry timestamp in the browser's local timezone.
10. He selects Download Code Sheet and chooses the card format. The server renders a print-ready PDF of 200 cards, four per US Letter page: each card carries the code in large monospaced type with dash grouping, the app address, and the "no name, no email, ever" line in English plus the four most common languages for that partner's caseload — a per-partner setting chosen from the fourteen locales.
11. The download is audited: actor, batch, format, and timestamp. Downloading the sheet again within the 72-hour window is permitted and audited each time.
12. He also downloads the CSV manifest, which contains the display prefix and status of each seat but never the full code. This is what he keeps for reconciliation.
13. He prints the sheets, cuts the cards, and delivers them to the Kentucky Refugee Ministries intake office.
14. Two days later the 72-hour window closes and the encrypted object is deleted by its lifecycle rule. From this point the codes exist only on the printed cards.
15. Kentucky Refugee Ministries staff distribute cards at intake appointments over the following six weeks. Each redemption moves its seat from issued to redeemed and increments the batch's activation figures, visible to both David and the partner's own administrators.

Failure and edge branches from J2.

4.13.3 Journey J3 — A content editor publishes a new module #

Actor. Priya, instructional designer, holding content_editor. She is adding a thirteenth module, "Returning an Item to a Store", after the launch twelve.

1. Priya signs in and lands on the module list, which shows all modules in every state with their translation coverage and publish status.
2. She selects Create Module and provides the module_key (store-return), the English title, the setting description, and the scenario summary. The module_key is validated as lowercase kebab- case, unique, and immutable after creation.
3. The module is created in draft. Draft modules are invisible to learners; a learner request for one returns NOT_FOUND, never FORBIDDEN (condition C4).
4. She uploads the scenario video, delivered by the production vendor against the specification in Section 13. The upload is multipart and resumable. On completion a background job transcodes it to the four-rendition HLS ladder and reports progress in the interface.
5. Transcoding completes in eleven minutes. The module page shows the renditions, durations, and a preview player. Had the source failed the vendor acceptance checks in Section 13.7 — wrong codec, wrong aspect ratio, insufficient bitrate, missing audio track — the job would have failed with the specific check named, and the asset would remain unpublishable.
6. She authors the three levels. For guided she writes the scaffolded lines. For practice she defines five required information items the learner must supply — the item being returned, the reason, whether they have a receipt, the desired outcome, and the date of purchase. For real-world she defines the curveball: the receipt is out of the return window and the clerk offers store credit instead of a refund.
7. She configures the bot persona per level: name, role, register, patience, and speaking rate. The fields and their effect on the system prompt are canonical in Section 14.4 and Section 16.3.
8. She writes the hint ladder for each level — three rungs, from a nudge to a full model answer, per Section 14.7.
9. She previews the module at each level (condition C6). The preview runs a real voice session against a synthetic preview seat, is visibly labeled as a preview, writes no progression and no learner analytics, and is metered against the preview budget line in Section 31.6.
10. Preview reveals that at real-world the bot resolves the curveball too quickly. She increases the persona's persistence and re-previews. The turn behaves correctly.
11. She writes the English source strings for the module — title, description, level names, hints, and glossary entries — against the writing standard in Section 21.3.
12. She exports the translation bundle for the module and sends it to the translation vendor. The export is a standard ICU-formatted bundle covering exactly the untranslated keys for the thirteen support languages.
13. Translations return over nine days and she imports them. The import validates ICU syntax, placeholder parity against the English source, and script direction. Two Arabic strings fail placeholder parity — a missing {count} — and the import rejects those two keys individually while accepting the rest, naming the failures precisely.
14. She corrects the two strings with the translation coordinator and re-imports. Coverage reaches 100% for all fourteen locales.
15. She uploads WebVTT caption files for all fourteen locales. The system validates timing, encoding, and that no cue exceeds the reading-rate limit in Section 13.5.
16. She moves the module to in_review. A second Content Editor reviews it. Review is a required state transition, not an optional courtesy; publishing directly from draft is rejected.
17. The reviewer approves. She selects Publish. The server evaluates every gate in condition C10: translation coverage at or above the gate for all fourteen locales, all three levels configured with required items, video transcoded, captions present in all fourteen locales.
18. A gate fails: the Kinyarwanda caption file is missing. Publication is refused with PUBLISH_GATE_FAILED and details.gate set to the caption gate, naming Kinyarwanda. The interface shows exactly which gate failed and what to do.
19. She uploads the missing caption file and republishes. All gates pass. She is prompted for a fresh TOTP step-up and provides it.
20. The module version is published atomically. It becomes visible to every learner on their next library load — no deploy, no release, no engineering involvement (failure condition X11 is what this step exists to avoid).
21. An audit entry records the publisher, the module, the version identifier, and the gate results.
22. Two days later a learner reports through a caseworker that one Somali hint reads oddly. Priya edits the string, which creates a new draft version; the published version is immutable (condition C9). She publishes the correction, and the previous version remains available for rollback.

4.13.4 Journey J4 — A partner administrator discovers a batch has low activation #

Actor. Maria, ESL program coordinator at Catholic Charities of Louisville, holding partner_admin scoped to that organization. Her partner issued a 150-seat batch labeled "Spring Cohort — Newcomer Academy" five weeks ago.

1. Maria signs in and lands on her partner overview. Every figure on this page is scoped to Catholic Charities by the query layer in Section 4.9; there is no control anywhere in the interface that would let her see another partner, and the underlying queries could not return one if there were.
2. The overview shows four batches. Three sit between 58% and 66% activation. "Spring Cohort — Newcomer Academy" sits at 19%. The batch is flagged, because the dashboard flags any batch more than 21 days old whose activation is more than 20 percentage points below the partner's trailing 90-day average (Section 26.4).
3. She opens the batch. It shows 150 issued, 28 redeemed, 22 active in the last 7 days, 0 revoked, 0 expired, issued 37 days ago, expiring in 328 days.
4. She opens the seat list. Each row shows the four-character display prefix, the status, the redemption date if any, and a coarse activity indicator — active this week, active this month, or no recent activity. There is no learner name, no score, no transcript, and no session history, because none of that is available to any role (matrix row 10, principle P9).
5. She compares against a healthy batch: "Winter Cohort" reached 40% activation by day 14 and 64% by day 37. The gap is in the first two weeks, which points at distribution rather than at the product.
6. She checks the redemption timing histogram. In healthy batches, most redemptions occur within three days of the card being handed over. In this batch, redemptions are spread thinly across five weeks with no early cluster, which is the signature of cards sitting in a folder rather than being handed out.
7. She reads the batch's distribution note: "For Newcomer Academy orientation, week of March 3." She checks with the orientation lead and learns the cards were placed in welcome folders rather than handed over with a verbal explanation.
8. She takes three actions. First, she downloads the aggregate CSV for the batch — a step-up TOTP prompt appears and she completes it, and the export is audited. Second, she briefs the orientation team to hand cards over directly with a thirty-second explanation, the pattern that produced the Winter Cohort's early cluster. Third, she adds a note to the batch recording what changed and when, so the next person reading this page has the context.
9. She does not revoke the batch. Unredeemed seats remain valid for another 328 days, and the remedy for low activation is distribution practice, not revocation.
10. Three weeks later the batch reaches 47% activation, the flag clears automatically, and the redemption histogram shows the expected early cluster for the newly distributed cards.

What Maria could not do at any point in J4, and the enforcement.

4.13.5 Journey J5 — A platform administrator onboards a partner and offboards a departing staff member #

Actor. David, holding platform_admin. A new partner, Americana Community Center, is joining with 300 funded seats. Separately, a Kentucky Refugee Ministries coordinator is leaving that organization this Friday.

Part one — onboarding the partner.

1. David opens Partners and selects Create Partner. He provides the display name, a short internal description, a primary language set for printed code sheets — Spanish, Swahili, Kinyarwanda, and Arabic — and a seat allocation of 300.
2. A TOTP step-up is required and he provides it. The partner is created with 0 seats issued and 300 remaining. An audit entry records the actor, the partner, and the initial allocation.
3. He invites the partner's first administrator following Section 4.11: work email, display name, role partner_admin, partner Americana Community Center. The invitation email is sent.
4. The invitee accepts within two days, sets a password, enrolls TOTP, saves recovery codes, and lands on her partner overview — which is empty, and says so in plain language with the single next action available to her: issue your first batch (principle P10).
5. She issues her first batch of 100 seats herself, within her partner's allocation, following the same path as Section 4.13.2 steps 3 through 12 but scoped to her own organization by condition C7.
6. She invites a second partner_admin and one auditor within her own organization, which condition C13 permits. She cannot invite a Content Editor or a Platform Administrator, and those options do not appear in her role selector.

Part two — offboarding the departing coordinator.

1. David receives notice that the Kentucky Refugee Ministries coordinator is leaving on Friday. That partner has two other active administrators, so the offboarding is routine.
2. On Friday he opens Staff, filters to Kentucky Refugee Ministries, and selects the departing account. The page shows the role, the invitation date, the last sign-in, and a summary of audited actions — batches issued, seats revoked, exports downloaded.
3. He selects Deactivate, provides a short reason, and completes the TOTP step-up.
4. The transaction in Section 4.12 step 3 executes: deleted_at set, status deactivated, token_version incremented, refresh tokens deleted, TOTP secret and recovery-code hashes deleted, password hash nulled, audit entry written.
5. The coordinator's browser is open at the time. Her current request completes normally. Her next request — a dashboard poll thirty seconds later — returns 401 ACCOUNT_DEACTIVATED. The client clears in-memory state and shows the sign-in screen with a neutral notice that the account is no longer active.
6. The other two Kentucky Refugee Ministries administrators receive a notification email naming who was deactivated, by whom, and when.
7. The batches she issued are untouched. They belong to the partner organization, remain fully manageable by her colleagues, and every learner seat in them continues to work.
8. The audit log still resolves her display name on every historical entry, because the row was deactivated rather than deleted. An audit trail that pointed at a missing actor would not be an audit trail.
9. Six months later she returns to the same organization. David does not reactivate the old row; he issues a fresh invitation, which creates a new account with a new identifier. The gap in her access is permanently visible in the record, which is the intended property.

4.14 Session and step-up summary by role #

This table consolidates, for implementation convenience, the session parameters stated in Sections 4.2 through 4.6. Where it appears to differ from a role subsection, this table governs. Password hashing parameters, lockout thresholds, and TOTP configuration are canonical in Section 29.3.

Step-up mechanics. A step-up is a fresh TOTP verification. A successful verification stamps the server-side session with a stepUpAt timestamp. An endpoint requiring step-up rejects the request with 401 STEP_UP_REQUIRED when stepUpAt is absent or older than 10 minutes; the client presents the TOTP prompt, verifies, and retries the original request once, automatically, preserving the form state. A step-up never re-prompts for the password.

Learners never receive a step-up prompt. There is no second factor a learner could present, and inventing one would require collecting something to bind it to, which Section 2.7 forbids. Learner actions with irreversible effect — seat erasure and replacing a bound device — are protected by explicit, localized, two-step confirmation instead, per Sections 29.10 and 8.5.

5. Technology Stack and System Architecture #

This section is the canonical owner of every technology choice, every deployable unit, the monorepo layout, the build outputs, the runtime topology, and the import boundary rules. Other sections reference this section by number and do not restate its contents.

5.1 Architectural Principles #

These principles are binding. Where a later design decision conflicts with one of them, the principle wins and the design must change.

5.2 The Complete Technology Stack #

Versions in the tables below are pinned exact in package.json (no ^, no ~) except where a range is explicitly stated. The pinning and upgrade policy is in Section 5.2.7 and the dependency policy is in Section 6.20.

5.2.1 Learner Progressive Web App #

5.2.2 Administrative Single-Page Application #

The partner dashboard and the content management system are two route trees inside one SPA bundle, served from one hostname and gated by role. They are not a PWA, are not installable, and are desktop-first.

5.2.3 Backend Services #

5.2.4 Data and Infrastructure #

5.2.5 Artificial Intelligence and Speech Vendors #

Section 10 owns the per-language vendor assignment. Section 15 owns the streaming pipeline. Section 16 owns prompt construction and safety. This subsection owns only the client-side technology facts and the hard parameter constraints that every calling service must obey.

Hard constraints on every language-model call. A violation is a build-blocking defect.

5.2.6 Shared Tooling #

5.2.7 Runtime Version Pinning and Lockfile Policy #

The following is normative and enforced by continuous integration.

Node.js. The repository targets Node.js 22.12.0 exactly. It is declared in three places that MUST agree:

.nvmrc                    ->  22.12.0
package.json  engines     ->  see below
Dockerfile    FROM        ->  node:22.12.0-bookworm-slim   (build stage)
                              node:22.12.0-bookworm-slim   (runtime stage, non-root user)

pnpm. The repository targets pnpm 9.15.0 exactly, activated through Corepack. Contributors do not install pnpm globally; corepack enable plus the packageManager field is the only supported path.

The exact engines and packageManager fields of the root package.json:

{
  "name": "louisville-voice",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=22.12.0 <23.0.0",
    "pnpm": ">=9.15.0 <10.0.0",
    "npm": "please-use-pnpm",
    "yarn": "please-use-pnpm"
  }
}

The npm and yarn entries are deliberate sentinels: they are not valid semantic-version ranges, so any attempt to install with npm or Yarn fails immediately with a readable message instead of silently producing a second lockfile.

Root .npmrc (committed):

engine-strict=true
node-linker=isolated
auto-install-peers=false
strict-peer-dependencies=true
save-exact=true
resolution-mode=highest
prefer-workspace-packages=true
link-workspace-packages=true

Lockfile policy.

5.3 Service Topology #

The system consists of four deployable runtime services, two statically hosted browser applications, three managed data stores, and a set of external vendors. Nothing else is deployed.

5.3.1 Deployable Units #

Each of the four runtime services is a separate container image built from the same repository. The learner and administrative applications are build artifacts, not servers; they are uploaded to object storage and served through the content delivery network.

5.3.2 Managed Data Stores #

5.3.3 External Vendors and Egress #

All vendor egress leaves through a network address translation gateway with a fixed set of addresses, so vendor allowlists are stable. Vendor credentials are injected as environment variables from the secrets manager at task start and are never present in an image, a repository, or a log line.

5.3.4 Hostnames Per Environment #

Canonical API path shapes are fixed by Section 6.2: the learner API is under /v1/, the administrative API is under /v1/admin/, and the practice WebSocket is /v1/practice on the voice gateway host.

5.4 Architecture Diagrams #

5.4.1 Whole System #

graph TB
  subgraph Clients["Client tier"]
    PWA["Learner PWA<br/>React 19 + Vite<br/>service worker: shell only"]
    ADM["Admin SPA<br/>dashboard + CMS route trees"]
  end

  subgraph Edge["Edge tier"]
    CF["CloudFront<br/>static bundles + HLS media<br/>signed cookies for segments"]
    ALB["Application Load Balancer<br/>TLS 1.3 termination, HSTS"]
  end

  subgraph Compute["Compute tier - ECS Fargate, arm64"]
    API["API service<br/>Fastify 5"]
    VOICE["Voice gateway service<br/>Fastify 5 + WebSocket"]
    WORK["Worker service<br/>BullMQ consumers"]
  end

  subgraph Data["Data tier"]
    PG[("PostgreSQL 17<br/>primary + read replica")]
    RD[("Redis 7.4<br/>sessions, limits, queue,<br/>ephemeral voice state")]
    S3[("Object storage<br/>us-east-2")]
  end

  subgraph Vendors["External vendors"]
    LLM["Anthropic<br/>claude-opus-5 / claude-haiku-4-5"]
    ASR["ASR: Deepgram Nova-3<br/>Google STT v2 / OpenAI"]
    TTS["TTS: ElevenLabs Flash v2.5<br/>Google TTS / Azure Speech"]
    PRON["Azure Pronunciation<br/>Assessment"]
  end

  PWA -->|"HTTPS /v1/*"| CF
  ADM -->|"HTTPS /v1/admin/*"| CF
  CF -->|"static bundles, HLS segments"| S3
  PWA -->|"HTTPS API calls"| ALB
  ADM -->|"HTTPS API calls"| ALB
  PWA -->|"WSS /v1/practice"| ALB
  ALB --> API
  ALB --> VOICE
  API --> PG
  API --> RD
  API -->|"presign, metadata"| S3
  VOICE -->|"read-only role"| PG
  VOICE --> RD
  VOICE --> LLM
  VOICE --> ASR
  VOICE --> TTS
  VOICE -->|"enqueue turn record"| RD
  WORK --> PG
  WORK --> RD
  WORK --> S3
  WORK --> LLM
  WORK --> PRON

5.4.2 Request Path for a Normal API Call #

The example is GET /v1/modules with a valid learner session.

sequenceDiagram
  autonumber
  participant B as Browser - TanStack Query
  participant SW as Service Worker
  participant CDN as CloudFront
  participant LB as Load Balancer
  participant API as API service - Fastify
  participant RD as Redis
  participant PG as PostgreSQL

  B->>SW: fetch /v1/modules
  Note over SW: API requests are never cached.<br/>Pass through unchanged.
  SW->>LB: HTTPS GET /v1/modules<br/>Authorization: Bearer <access JWT><br/>Accept-Language: ps
  LB->>API: forward, add X-Forwarded-For
  Note over API: onRequest hook mints ULID requestId,<br/>binds it to the async context and the logger
  API->>API: verify access JWT signature, expiry, audience
  API->>RD: INCR rate-limit bucket for session
  RD-->>API: current count
  alt limit exceeded
    API-->>B: 429 error envelope RATE_LIMITED, retryable true
  else within limit
    API->>API: Zod parse of query params (limit, cursor, locale)
    API->>PG: SELECT published modules + localized titles
    PG-->>API: rows
    API->>API: Zod serialize response, attach meta.requestId,<br/>meta.serverTime, meta.nextCursor, meta.hasMore
    API-->>B: 200 success envelope
  end
  Note over B: TanStack Query caches by<br/>[modules, locale] and revalidates on focus

Binding rules visible in this path:

1. The service worker never caches an API response. It caches only the application shell, fonts, icons, and locale bundles (Section 23).
2. The request identifier is minted at the first server-side hop and echoed in meta.requestId of every response, success or failure (Section 6.3 and Section 6.4).
3. Rate limiting is evaluated before any database work.
4. Every response body is produced by serializing through the response schema, so an accidental extra field is stripped rather than leaked.

5.4.3 Request Path for a Voice Practice Turn #

sequenceDiagram
  autonumber
  participant B as Browser
  participant API as API service
  participant LB as Load Balancer
  participant VG as Voice gateway
  participant RD as Redis
  participant ASR as ASR vendor
  participant LLM as Anthropic
  participant TTS as TTS vendor
  participant Q as Job queue
  participant W as Worker

  B->>API: POST /v1/practice-sessions {moduleKey, levelKey}
  API->>API: check level unlocked, seat active, flags
  API->>RD: create ephemeral session state, TTL 30 min
  API-->>B: 201 {practiceSessionId, voiceTicket, wsUrl}
  Note over B,API: voiceTicket is single-use, 60 s lifetime,<br/>bound to practiceSessionId and device

  B->>LB: WSS CONNECT /v1/practice?ticket=...
  LB->>VG: upgrade
  VG->>RD: validate and burn ticket, load session state
  VG-->>B: control frame {type:"ready", turn:1, config}

  loop each learner turn
    B-)VG: binary frames, Opus 20 ms, ~24 kbit/s
    VG-)ASR: stream audio
    ASR--)VG: partial transcripts
    VG--)B: control frame {type:"partial", text}
    B-)VG: control frame {type:"endOfSpeech"}
    ASR--)VG: final transcript + word timings
    VG->>VG: injection screening and safety gate (Section 16)
    VG->>LLM: streaming dialogue turn,<br/>cached system prompt, adaptive thinking, low effort
    LLM--)VG: streamed sentences
    VG-)TTS: stream sentence-by-sentence as they complete
    TTS--)VG: audio chunks
    VG--)B: binary TTS frames + control frame {type:"botTurn", text}
    VG->>RD: append turn to ephemeral session state
  end

  B->>VG: control frame {type:"complete"}
  VG->>Q: enqueue scoring job {practiceSessionId}
  VG-->>B: control frame {type:"closing", reason:"complete"}
  VG->>B: WebSocket close 1000
  W->>Q: dequeue
  W->>W: pronunciation assessment + rubric scoring (Sections 15, 17)
  W->>W: persist attempt, score, unlocks, badges (Sections 17, 18)
  B->>API: GET /v1/practice-sessions/{id}/result (polled)
  API-->>B: 200 score, mastery state, badges awarded

Binding rules visible in this path:

1. The WebSocket is authorized by a single-use ticket issued over the ordinary HTTPS API, not by an access token in a query string or a subprotocol header. Tickets expire 60 seconds after issue and are burned atomically in Redis on first use.
2. Text-to-speech synthesis begins on the first completed sentence of the model response, not on the completed response. This is the largest single lever on perceived latency.
3. The voice gateway never writes to learner progress tables. It enqueues; the worker persists.
4. Raw learner audio is never written to durable storage from this path. Retention rules are owned by Section 29.

5.4.4 Video Delivery Path #

sequenceDiagram
  autonumber
  participant Staff as Content staff - Admin SPA
  participant API as API service
  participant S3 as Object storage
  participant W as Worker
  participant CDN as CloudFront
  participant B as Learner browser

  rect rgb(245,245,245)
  Note over Staff,W: Publish path (asynchronous, minutes)
  Staff->>API: POST /v1/admin/assets/uploads (filename, sizeBytes, checksum)
  API-->>Staff: 201 presigned multipart upload target, assetId
  Staff->>S3: multipart PUT of source master to the private source bucket
  Staff->>API: POST /v1/admin/assets/{assetId}/complete
  API->>W: enqueue package-video job
  W->>S3: read source master
  W->>W: transcode ladder 240p/360p/540p/720p, CMAF fMP4,<br/>H.264 High, AAC-LC, WebVTT captions per locale (Section 13)
  W->>S3: write renditions, master playlist, captions, poster
  W->>API: mark asset READY, record durations and checksums
  end

  rect rgb(245,245,245)
  Note over B,CDN: Playback path (synchronous, milliseconds)
  B->>API: GET /v1/modules/{moduleKey}/video
  API->>API: verify seat active and module published
  API-->>B: 200 {masterPlaylistUrl, captionTracks[], posterUrl}<br/>+ Set-Cookie CloudFront-Policy / -Signature / -Key-Pair-Id<br/>Domain=cdn.louisvillevoice.org, HttpOnly, Secure, SameSite=None<br/>attributes, lifetime and renewal per Section 24.13
  B->>CDN: GET master.m3u8 (cookies attached)
  CDN->>CDN: verify signed cookie policy and path scope
  CDN->>S3: origin fetch via origin access control (cache miss only)
  S3-->>CDN: playlist
  CDN-->>B: playlist
  loop adaptive playback
    B->>CDN: GET segment .m4s at chosen rendition
    CDN-->>B: segment (edge cache hit after first learner)
  end
  end

Binding rules visible in this path:

1. The signed cookie is scoped, per Section 24.13, to the media hostname and to the path prefix of the requested module's asset directory. One cookie set authorizes every rendition and caption of that module and nothing else. The media host is not the application host, so every segment request is cross-site: the cookie must carry SameSite=None, and a browser rejects None unless Secure is also set. A Lax cookie is never sent on a cross-site subresource request, which would fail the first segment with a 403 and break playback for every learner.
2. The learner browser never receives an object-storage credential and never talks to object storage directly. Origin access control makes the storage bucket unreadable except through the content delivery network.
3. Cookie attributes, lifetime, and renewal are owned by the video endpoint in Section 24.13 and are not restated here. Expiry mid-playback triggers a silent re-request of that endpoint and a player retry, not an error screen.
4. Segments are cached at the edge for 30 days with immutable cache-control, because a published rendition is never mutated in place; republishing writes a new versioned path.

5.5 Why the Voice Transport Is a WebSocket and Not WebRTC #

The realtime voice path uses a WebSocket carrying binary Opus frames upstream and binary synthesized audio plus JSON control frames downstream. This is a deliberate choice over WebRTC, and it has a real cost.

5.5.1 The Comparison #

5.5.2 The Honest Tradeoff #

WebRTC is genuinely better on raw transport latency and genuinely better under packet loss. On a degraded mobile connection, a WebSocket turn can stall for the duration of a TCP retransmission where a WebRTC turn would produce a short audio artifact and continue. We accept that cost for four reasons:

1. The conversation is turn-based, not full-duplex. The learner speaks, then the coach speaks. There is no simultaneous two-way audio, so the interactive-latency requirement that justifies WebRTC's complexity does not apply. The dominant term in perceived latency is speech-recognition finalization plus model time-to-first-sentence plus synthesis start — measured in hundreds of milliseconds — not the 50 ms transport difference.
2. Our users are frequently on restrictive networks. Practice happens in libraries, resettlement agency offices, clinic waiting rooms, and community centers. A transport that works everywhere on port 443 is worth more to this audience than 50 ms.
3. Operational surface is a real budget line. This system is built and maintained by a small team. A media server tier is an entire additional operational discipline, and every hour spent on it is an hour not spent on content and accessibility.
4. We already bridge to vendors server-side. Speech recognition and synthesis both terminate at our gateway regardless of client transport, so WebRTC would not remove a hop; it would add a media-handling layer in front of the same bridge.

5.5.3 Mitigations We Are Required to Implement #

5.5.4 The Condition That Would Reverse This Decision #

This decision is revisited only if a future release introduces genuine full-duplex conversation — that is, barge-in where the learner interrupts the coach mid-sentence and both audio directions are live simultaneously — and measured stall rates on the WebSocket path exceed 2% of turns for more than 5% of sessions over a 30-day window. Both conditions must hold. Neither condition is met by the launch scope in this document, so WebRTC is out of scope, and no code may be written to accommodate a future WebRTC path.

5.6 Monorepo Layout #

One Git repository. pnpm workspaces plus Turborepo. Applications live under apps/, shared libraries under packages/, shared build configuration under tooling/, and operational assets under infra/, db/, and scripts/.

5.6.1 Full Directory Tree #

louisville-voice/
├── .github/
│   └── workflows/
│       ├── ci.yml                     # lint, typecheck, unit, build, boundary check, audit
│       ├── e2e.yml                     # Playwright against an ephemeral stack
│       ├── deploy-dev.yml              # auto on merge to main
│       ├── deploy-staging.yml          # auto on merge to main after dev is green
│       ├── deploy-production.yml       # manual approval gate
│       └── renovate-validate.yml       # validates the Renovate configuration
├── .nvmrc                              # 22.12.0
├── .npmrc                              # engine-strict, isolated linker, save-exact
├── package.json                        # private root; engines and packageManager fields
├── pnpm-workspace.yaml                 # apps/*, packages/*, tooling/*
├── pnpm-lock.yaml                      # the single lockfile
├── turbo.json                          # task graph and cache inputs/outputs
├── lefthook.yml                        # pre-commit: format, lint staged, gitleaks
├── commitlint.config.js                # Conventional Commits enforcement
├── eslint.config.js                    # flat config, root of the shared rule set
├── .prettierrc.json
├── tsconfig.base.json                  # compiler options every package extends
├── docker-compose.yml                  # local Postgres, Redis, object storage emulator
│
├── apps/
│   ├── learner-pwa/                    # the installable learner client
│   │   ├── index.html
│   │   ├── vite.config.ts              # PWA plugin, injectManifest, manual chunks
│   │   ├── public/
│   │   │   ├── manifest.webmanifest
│   │   │   └── icons/                  # maskable icons, 192/512/1024
│   │   ├── src/
│   │   │   ├── main.tsx                # entry: providers, router, i18n bootstrap
│   │   │   ├── sw.ts                   # hand-written service worker (Section 23)
│   │   │   ├── app/
│   │   │   │   ├── router.tsx          # createBrowserRouter route tree (Section 19)
│   │   │   │   ├── providers.tsx       # QueryClient, i18n, direction, error boundary
│   │   │   │   └── error-boundary.tsx
│   │   │   ├── features/               # one folder per product capability
│   │   │   │   ├── seat-redemption/
│   │   │   │   ├── module-library/
│   │   │   │   ├── video-player/
│   │   │   │   ├── practice/           # WebSocket client, audio capture, turn UI
│   │   │   │   ├── progress/
│   │   │   │   └── badges/
│   │   │   ├── api/
│   │   │   │   ├── client.ts           # typed fetch wrapper, envelope unwrapping
│   │   │   │   ├── query-keys.ts       # the single query-key factory
│   │   │   │   └── hooks/              # one generated-shape hook per endpoint
│   │   │   ├── stores/                 # Zustand stores (UI-only state)
│   │   │   ├── styles/
│   │   │   │   └── index.css           # Tailwind entry and design tokens import
│   │   │   └── lib/                    # client-only helpers with no domain logic
│   │   ├── tests/
│   │   │   └── e2e/                    # Playwright specs
│   │   └── package.json
│   │
│   ├── admin/                          # partner dashboard + CMS, one bundle
│   │   ├── index.html
│   │   ├── vite.config.ts              # no PWA plugin
│   │   ├── src/
│   │   │   ├── main.tsx
│   │   │   ├── app/router.tsx          # /dashboard/* and /cms/* trees, role-gated
│   │   │   ├── features/
│   │   │   │   ├── auth/               # password + mandatory TOTP
│   │   │   │   ├── partners/
│   │   │   │   ├── seat-batches/
│   │   │   │   ├── analytics/          # Recharts views (Section 26)
│   │   │   │   ├── content-modules/    # CMS module and level editing (Section 27)
│   │   │   │   ├── translations/       # translation workbench (Section 9)
│   │   │   │   └── assets/             # video upload and publish (Section 13)
│   │   │   ├── api/
│   │   │   └── lib/
│   │   ├── tests/e2e/
│   │   └── package.json
│   │
│   ├── api/                            # Fastify HTTP service
│   │   ├── src/
│   │   │   ├── server.ts               # buildServer(): plugin registration only
│   │   │   ├── index.ts                # boot: config validation, listen, graceful shutdown
│   │   │   ├── plugins/
│   │   │   │   ├── request-context.ts  # ULID requestId, AsyncLocalStorage binding
│   │   │   │   ├── logging.ts          # pino, redaction paths
│   │   │   │   ├── error-handler.ts    # the single error envelope producer
│   │   │   │   ├── auth-learner.ts     # access JWT verification
│   │   │   │   ├── auth-staff.ts       # staff session + role guard
│   │   │   │   ├── rate-limit.ts
│   │   │   │   ├── security-headers.ts # helmet, HSTS, CSP
│   │   │   │   └── openapi.ts          # spec generation from route schemas
│   │   │   ├── routes/
│   │   │   │   ├── v1/                 # learner endpoints (Section 24)
│   │   │   │   └── v1-admin/           # admin endpoints (Section 25)
│   │   │   ├── services/               # domain logic; no Fastify types allowed here
│   │   │   ├── repositories/           # the only place Drizzle queries are written
│   │   │   └── jobs/                   # job producers (enqueue only, never consume)
│   │   ├── tests/
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   ├── voice-gateway/                  # WebSocket practice service
│   │   ├── src/
│   │   │   ├── index.ts
│   │   │   ├── server.ts
│   │   │   ├── ws/
│   │   │   │   ├── connection.ts       # upgrade, ticket burn, lifecycle, heartbeat
│   │   │   │   ├── protocol.ts         # frame codec, validated by contracts schemas
│   │   │   │   └── backpressure.ts     # send-queue limits and drop policy
│   │   │   ├── pipeline/
│   │   │   │   ├── capture.ts          # inbound audio framing and buffering
│   │   │   │   ├── asr-stream.ts       # AsrProvider driver
│   │   │   │   ├── dialogue.ts         # Anthropic streaming turn
│   │   │   │   ├── tts-stream.ts       # TtsProvider driver, sentence-boundary chunking
│   │   │   │   └── turn-recorder.ts    # ephemeral state writes and job enqueue
│   │   │   ├── safety/                 # injection screening hooks (Section 16)
│   │   │   └── state/                  # Redis session-state accessors
│   │   ├── tests/
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   └── worker/                         # BullMQ consumers, no public ingress
│       ├── src/
│       │   ├── index.ts                # queue registration, health port, shutdown drain
│       │   ├── queues.ts               # queue names, concurrency, retry policy
│       │   ├── processors/
│       │   │   ├── score-attempt.ts
│       │   │   ├── evaluate-badges.ts
│       │   │   ├── package-video.ts
│       │   │   ├── ingest-captions.ts
│       │   │   ├── recompute-translation-status.ts
│       │   │   ├── rollup-analytics.ts
│       │   │   ├── generate-seat-batch.ts
│       │   │   ├── enforce-retention.ts
│       │   │   └── account-vendor-cost.ts
│       │   ├── schedules.ts            # repeatable job definitions with cron expressions
│       │   ├── repositories/
│       │   └── services/
│       ├── tests/
│       ├── Dockerfile
│       └── package.json
│
├── packages/
│   ├── contracts/                      # Zod schemas + inferred types + error codes
│   │   ├── src/
│   │   │   ├── index.ts                # the only public entry point
│   │   │   ├── envelope.ts             # success and error envelope schemas
│   │   │   ├── errors.ts               # ErrorCode union, catalogue, helpers
│   │   │   ├── primitives.ts           # Uuid, Ulid, Cursor, Timestamp, DurationMs, LocaleCode
│   │   │   ├── pagination.ts           # PageQuery, PageMeta
│   │   │   ├── domain/                 # entity schemas mirroring Section 7
│   │   │   ├── learner/                # request/response pairs for Section 24
│   │   │   ├── admin/                  # request/response pairs for Section 25
│   │   │   ├── voice/                  # WebSocket frame schemas for Section 15
│   │   │   └── jobs/                   # job payload schemas
│   │   └── package.json
│   │
│   ├── db/                             # Drizzle schema, migrations, seed data
│   │   ├── src/
│   │   │   ├── schema/                 # table definitions (Section 7 is canonical)
│   │   │   ├── client.ts               # pooled connection factory
│   │   │   └── enums.ts                # Postgres enum declarations
│   │   ├── migrations/                 # numbered .sql files, forward-only
│   │   ├── seeds/                      # per-environment seed scripts
│   │   ├── drizzle.config.ts
│   │   └── package.json
│   │
│   ├── i18n/                           # locale registry + translation catalogs
│   │   ├── src/
│   │   │   ├── locales.ts              # the 14 locales, direction, native names
│   │   │   ├── format.ts               # ICU helpers, number/date/list formatters
│   │   │   └── index.ts
│   │   ├── catalogs/
│   │   │   ├── en/ … ar/ ps/ es/ te/ ht/ rw/ sw/ fr/ ne/ so/ tr/ vi/ zh-Hans/
│   │   └── package.json
│   │
│   ├── ui/                             # shared React components and design tokens
│   │   ├── src/
│   │   │   ├── tokens/                 # color, type, spacing, motion (Section 20)
│   │   │   ├── primitives/             # vendored Radix-based primitives
│   │   │   ├── components/             # Button, Field, Dialog, Toast, ProgressRing …
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   ├── speech/                         # vendor abstraction for ASR, TTS, pronunciation
│   │   ├── src/
│   │   │   ├── types.ts                # AsrProvider, TtsProvider, PronunciationScorer
│   │   │   ├── registry.ts             # language -> provider resolution from config
│   │   │   ├── providers/
│   │   │   │   ├── deepgram/ google/ openai/ elevenlabs/ azure/
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   ├── scoring/                        # pure rubric math, no I/O (Section 17)
│   │   ├── src/
│   │   │   ├── rubric.ts
│   │   │   ├── mastery.ts              # threshold and unlock rules
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   ├── config/                         # environment schema and loader
│   │   ├── src/
│   │   │   ├── schema.ts               # Zod schema per service, no secret defaults
│   │   │   ├── load.ts                 # parse-or-exit at boot
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   ├── observability/                  # logger factory, tracing, metrics helpers
│   │   ├── src/
│   │   │   ├── logger.ts               # pino factory with redaction paths
│   │   │   ├── tracing.ts              # OpenTelemetry bootstrap
│   │   │   ├── metrics.ts
│   │   │   └── index.ts
│   │   └── package.json
│   │
│   └── testkit/                        # shared test factories and fixtures
│       ├── src/
│       │   ├── factories/              # builders returning fresh objects per call
│       │   ├── containers.ts           # Testcontainers helpers for Postgres and Redis
│       │   └── index.ts
│       └── package.json
│
├── tooling/
│   ├── eslint-config/                  # shared flat-config fragments
│   ├── tsconfig/                       # base, react, node variants
│   └── vitest-config/                  # shared Vitest defaults
│
├── infra/
│   └── terraform/
│       ├── modules/                    # network, ecs-service, rds, redis, cdn, waf
│       └── envs/{dev,staging,production}/
│
├── db/
│   └── README-less operational SQL/    # ad hoc analysis queries, reviewed like code
│
├── docs/
│   └── adr/                            # architecture decision records, numbered
│
└── scripts/
    ├── check-boundaries.ts
    ├── check-contract-sync.ts
    ├── check-i18n-keys.ts
    └── generate-openapi.ts

5.6.2 Package Purposes and Ownership #

5.7 The Shared Contracts Package: How Types Flow #

The contracts package is the spine of the system. A field exists in exactly one place; everything else derives from it. This subsection shows the complete flow for one endpoint.

5.7.1 Step 1 — The Schema Is the Source of Truth #

// packages/contracts/src/learner/modules.ts
import { z } from 'zod';
import { LocaleCode, Uuid, Timestamp } from '../primitives.js';
import { pageQuery, pageMeta } from '../pagination.js';

/** Stable, human-readable key for a practice module, e.g. "bus-pass". */
export const ModuleKey = z
  .string()
  .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'moduleKey must be kebab-case')
  .min(3)
  .max(48)
  .brand<'ModuleKey'>();
export type ModuleKey = z.infer<typeof ModuleKey>;

export const ModuleSummary = z.object({
  moduleId: Uuid,
  moduleKey: ModuleKey,
  order: z.number().int().min(1).max(999),
  title: z.string().min(1).max(120),
  settingLabel: z.string().min(1).max(160),
  posterUrl: z.string().url(),
  videoDurationMs: z.number().int().nonnegative(),
  highestUnlockedLevel: z.enum(['guided', 'practice', 'real-world']),
  masteredAt: Timestamp.nullable(),
  requiresDisclaimer: z.boolean(),
});
export type ModuleSummary = z.infer<typeof ModuleSummary>;

export const ListModulesQuery = pageQuery.extend({
  locale: LocaleCode.optional(),
});
export type ListModulesQuery = z.infer<typeof ListModulesQuery>;

export const ListModulesResponse = z.object({
  data: z.array(ModuleSummary),
  meta: pageMeta,
});
export type ListModulesResponse = z.infer<typeof ListModulesResponse>;

Three properties of this file are binding:

1. Branded primitives. ModuleKey is a branded string, so a raw string cannot be passed where a ModuleKey is expected. The same applies to Uuid, Ulid, Cursor, and LocaleCode (see Section 6.7).
2. Request and response are both schemas. The response is validated on the way out, not merely typed.
3. No optional fields without a stated default. A field is either required, or explicitly .nullable(), or .optional() with the default written into the schema via .default(...). "Sometimes present, sometimes absent, meaning unstated" is prohibited.

5.7.2 Step 2 — The Server Handler Derives Its Types #

// apps/api/src/routes/v1/modules.ts
import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
import { ListModulesQuery, ListModulesResponse } from '@lv/contracts';
import { errorResponses } from '../../plugins/error-handler.js';
import { listModulesForSeat } from '../../services/modules.service.js';

export const modulesRoutes: FastifyPluginAsyncZod = async (app) => {
  app.get(
    '/modules',
    {
      schema: {
        operationId: 'listModules',
        tags: ['modules'],
        querystring: ListModulesQuery,
        response: {
          200: ListModulesResponse,
          ...errorResponses(['UNAUTHENTICATED', 'SEAT_REVOKED', 'RATE_LIMITED']),
        },
      },
      onRequest: [app.requireLearnerSession],
    },
    async (request) => {
      // request.query is fully typed and already validated: no casting, no `as`.
      const { limit, cursor, locale } = request.query;
      return listModulesForSeat({
        seatId: request.learner.seatId,
        locale: locale ?? request.learner.locale,
        limit,
        cursor,
      });
    },
  );
};

The handler never declares an interface. request.query is ListModulesQuery because the type provider infers it from the schema. The return value is checked against ListModulesResponse at compile time and serialized through it at runtime, which strips any field the schema does not declare.

5.7.3 Step 3 — The Generated Client Surface #

A single generated module maps each operationId to its request and response types. Generation runs in the build graph, so it cannot fall behind.

// apps/learner-pwa/src/api/hooks/use-modules.ts
import { useQuery } from '@tanstack/react-query';
import type { ListModulesQuery, ListModulesResponse } from '@lv/contracts';
import { apiClient } from '../client.js';
import { queryKeys } from '../query-keys.js';

export function useModules(params: ListModulesQuery) {
  return useQuery({
    queryKey: queryKeys.modules.list(params),
    queryFn: ({ signal }) =>
      apiClient.get<ListModulesResponse>('/v1/modules', { query: params, signal }),
    staleTime: 5 * 60 * 1000,
  });
}

// apps/learner-pwa/src/api/client.ts  (the only place fetch is called)
import { ErrorEnvelope, SuccessEnvelope } from '@lv/contracts';
import { ApiError } from './api-error.js';

async function request<T>(method: string, path: string, init: RequestInit & { query?: unknown }) {
  const response = await fetch(buildUrl(path, init.query), { ...init, method, credentials: 'include' });
  const body: unknown = await response.json();

  if (!response.ok) {
    const parsed = ErrorEnvelope.safeParse(body);
    if (!parsed.success) throw ApiError.malformed(response.status, body);
    throw ApiError.fromEnvelope(parsed.data); // carries code, messageKey, retryable
  }

  const parsed = SuccessEnvelope.safeParse(body);
  if (!parsed.success) throw ApiError.malformed(response.status, body);
  return parsed.data.data as T;
}

Everything downstream — the form resolver, the mutation, the error toast — reads from the same schema. The client's retry policy reads retryable from the parsed error envelope; it does not maintain its own list of retryable status codes.

5.7.4 Step 4 — The Same Schema Serves the Form #

// apps/admin/src/features/content-modules/module-form.tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { UpdateModuleRequest } from '@lv/contracts';

const form = useForm<UpdateModuleRequest>({
  resolver: zodResolver(UpdateModuleRequest),
  mode: 'onBlur',
});

Client-side and server-side validation cannot diverge, because they are the same object. Field-level error messages are rendered from i18n keys derived from the field path, never from the raw Zod message (see Section 6.12.4).

5.7.5 How Frontend and Backend Stay in Sync #

Five mechanisms, all enforced in continuous integration. All five must pass before a merge.

The contract-sync check is exact:

pnpm --filter @lv/api run generate:openapi
git diff --exit-code apps/api/openapi.json
# non-empty diff => the branch is rejected with:
# "OpenAPI document is stale. Run pnpm generate:openapi and commit the result."

Additionally, scripts/check-contract-sync.ts asserts three invariants and fails on any violation:

1. Every route registered on the server declares both a request schema (or explicitly declares body: z.never()) and a 200/201 response schema.
2. Every error code referenced in a route's response map exists in the error catalogue of Section 6.5.
3. Every exported schema in the contracts package is reachable from src/index.ts; unreachable schemas are dead contract surface and fail the build.

5.8 Build Outputs #

Rules that apply to every build:

1. Libraries emit ESM only. There is no CommonJS output anywhere in the repository.
2. Every package sets "exports" with a single "." entry pointing at dist/index.js and dist/index.d.ts. Deep imports into another package's internals are impossible by construction.
3. Source maps are generated for every build and uploaded to the telemetry sink, never served from the public origin.
4. Application builds are deterministic: given the same commit and the same lockfile, chunk hashes are identical. Continuous integration verifies this by building twice on the release job and comparing the manifest.
5. Container images are multi-stage: a build stage that installs development dependencies and compiles, and a runtime stage that copies only dist/, production dependencies, and runs as a non-root user with a read-only root filesystem.

5.9 Runtime Topology per Environment #

Section 30 owns how these resources are provisioned. This subsection owns the numbers.

5.9.1 Compute #

5.9.2 Autoscaling Rules (production) #

Voice gateway scale-in must never terminate a task holding an open practice connection: tasks receive SIGTERM, stop accepting upgrades, and are given a 180-second drain window during which existing sessions finish. Any session still open at the end of the drain receives a {"type":"closing","reason":"serverShutdown"} control frame and a close code of 1001, and the client reconnects with a fresh ticket.

5.9.3 Data Stores #

5.9.4 Connection Budgets #

Connection pools are sized so that the sum of all maximum pool sizes stays below 80% of the database max_connections, leaving headroom for migrations and operator sessions.

5.10 Service Discovery and Networking #

There is no service mesh and no dynamic discovery library. Services address each other by stable DNS name, and the set of names is fixed per environment.

Health checks:

/healthz deliberately does not check dependencies. A database outage must not cause every task to be killed and replaced, which would turn a recoverable incident into a total outage.

5.11 Boundary Rules: What May Import What #

5.11.1 The Dependency Graph #

graph LR
  contracts["packages/contracts"]
  config["packages/config"]
  obs["packages/observability"]
  i18n["packages/i18n"]
  scoring["packages/scoring"]
  speech["packages/speech"]
  db["packages/db"]
  ui["packages/ui"]
  api["apps/api"]
  voice["apps/voice-gateway"]
  worker["apps/worker"]
  pwa["apps/learner-pwa"]
  admin["apps/admin"]

  config --> contracts
  db --> contracts
  speech --> contracts
  speech --> config
  speech --> obs
  scoring --> contracts
  ui --> i18n
  api --> contracts
  api --> db
  api --> config
  api --> obs
  api --> i18n
  api --> scoring
  voice --> contracts
  voice --> db
  voice --> config
  voice --> obs
  voice --> speech
  worker --> contracts
  worker --> db
  worker --> config
  worker --> obs
  worker --> speech
  worker --> scoring
  worker --> i18n
  pwa --> contracts
  pwa --> ui
  pwa --> i18n
  admin --> contracts
  admin --> ui
  admin --> i18n

5.11.2 The Rules, Stated Normatively #

5.11.3 Enforcement #

Boundaries are enforced by lint, not by convention. The relevant fragment of the flat ESLint configuration:

// eslint.config.js (excerpt)
import boundaries from 'eslint-plugin-boundaries';

export default [
  {
    plugins: { boundaries },
    settings: {
      'boundaries/elements': [
        { type: 'contracts',    pattern: 'packages/contracts/*' },
        { type: 'config',       pattern: 'packages/config/*' },
        { type: 'observability',pattern: 'packages/observability/*' },
        { type: 'db',           pattern: 'packages/db/*' },
        { type: 'speech',       pattern: 'packages/speech/*' },
        { type: 'scoring',      pattern: 'packages/scoring/*' },
        { type: 'i18n',         pattern: 'packages/i18n/*' },
        { type: 'ui',           pattern: 'packages/ui/*' },
        { type: 'testkit',      pattern: 'packages/testkit/*' },
        { type: 'server-app',   pattern: 'apps/(api|voice-gateway|worker)/*' },
        { type: 'browser-app',  pattern: 'apps/(learner-pwa|admin)/*' },
      ],
    },
    rules: {
      'boundaries/element-types': ['error', {
        default: 'disallow',
        rules: [
          { from: 'contracts',   allow: [] },
          { from: 'config',      allow: ['contracts'] },
          { from: 'scoring',     allow: ['contracts'] },
          { from: 'db',          allow: ['contracts'] },
          { from: 'speech',      allow: ['contracts', 'config', 'observability'] },
          { from: 'ui',          allow: ['i18n'] },
          { from: 'server-app',  allow: ['contracts', 'config', 'observability', 'db', 'speech', 'scoring', 'i18n'] },
          { from: 'browser-app', allow: ['contracts', 'ui', 'i18n'] },
        ],
      }],
      'boundaries/no-private': 'error',
    },
  },
];

scripts/check-boundaries.ts additionally asserts the acyclicity of the whole workspace dependency graph and the repository-specific rules B6, B7, B8, and B9, which are path-scoped rather than package-scoped. Both run in the ci workflow. A boundary violation is never suppressed with an inline disable comment; the lint configuration forbids disable comments for boundaries/* rules.

5.12 How a Change Flows from a Schema Edit to Production #

This walkthrough is normative: it is the required sequence for any change that touches a contract. The worked example adds an optional estimatedMinutes field to the module summary.

1. Branch. feat/module-estimated-minutes, cut from main (branch naming in Section 6.9.8).

2. Edit the schema. Add the field in the contracts package with an explicit nullability decision:

export const ModuleSummary = z.object({
  // …existing fields…
  estimatedMinutes: z.number().int().min(1).max(60).nullable(),
});

3. Typecheck immediately. pnpm typecheck now fails in every place that constructs a ModuleSummary. The compiler is producing the complete work list. There is no searching for call sites.

4. Migrate the database. Add the column to the Drizzle schema, then generate the migration:

pnpm --filter @lv/db exec drizzle-kit generate --name add_module_estimated_minutes
# => packages/db/migrations/0042_add_module_estimated_minutes.sql

Review the generated SQL by hand. Because a NOT NULL column cannot be added safely in one step (Section 6.13.4), this column is added nullable in this release. Verify the migration acquires no lock longer than 2 seconds.

5. Update the repository and service. The repository selects the new column; the service maps it. Both are typed, so omissions fail the build.

6. Regenerate the API specification.

pnpm --filter @lv/api run generate:openapi   # updates apps/api/openapi.json

7. Update the contract snapshot. pnpm test -- --update refreshes the JSON Schema snapshot. The diff is reviewed as part of the change; it is the human-readable record of what the contract now is.

8. Consume it in the client. The learner application renders the value; because the field is nullable, the component must handle null. The compiler enforces this.

9. Add tests. A unit test for the mapping, a repository test against a real database container, and a component test asserting the null case renders correctly.

10. Add or update the localized string. Any new user-facing text is added to the English source catalog with a new key, and the translation task is opened per Section 9. The scripts/check-i18n-keys.ts check fails if a key is referenced but missing from the English catalog.

11. Open a pull request. Continuous integration runs, in this order and all of them blocking:

12. Review and merge. At least one approving review. Merge to main is a squash merge; the squashed commit message must satisfy Conventional Commits (Section 6.9.7).

13. Automatic deployment to dev. On merge: images are built and tagged with the commit SHA, the migration task runs to completion, then the new task definitions are deployed. Migration failure aborts the deployment and leaves the previous version running.

14. Automatic promotion to staging. After the dev smoke suite passes, the identical images are deployed to staging. Images are never rebuilt for a new environment; the artifact that was tested is the artifact that is promoted.

15. Manual approval, then production. A named approver releases to production. The deployment is a rolling update with a minimum healthy percentage of 100 and a maximum of 200, so capacity never drops during a release. Automatic rollback triggers if the error rate exceeds the threshold defined in Section 31 within the 15-minute post-deployment observation window.

16. Contract phase two (a later release). If the field is to become mandatory, a subsequent release backfills every row, then a third release adds the NOT NULL constraint using the validated check-constraint procedure in Section 6.13.4 and tightens the Zod schema. Expand, migrate, contract — never in one release.

5.13 Local Development Topology #

One command brings up a complete, working system. This is a hard requirement: a contributor with a clean machine, Node.js 22.12.0, Corepack, and Docker must reach a working stack in under 10 minutes with no manual steps beyond those below.

corepack enable
pnpm install --frozen-lockfile
cp .env.example .env            # every non-secret default is filled in; secrets are blank
docker compose up -d            # postgres:17, redis:7.4, S3-compatible object storage emulator
pnpm db:migrate                 # applies every migration
pnpm db:seed                    # 12 modules, 3 levels each, 14 locales, sample seat batch
pnpm dev                        # turbo run dev: api, voice-gateway, worker, both browser apps

5.14 Failure Domains and Degraded Modes #

Every dependency has a defined degraded mode. "Show an error page" is a valid degraded mode only where listed.

6. Engineering Conventions and Standards #

This section is the canonical owner of every engineering convention in the system. Every other section references this section by number and does not restate its rules. Where any other part of this document appears to contradict this section, this section governs.

6.1 How to Read This Section #

The key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, SHOULD NOT, and MAY are used in their conventional normative sense. A MUST is enforced mechanically wherever mechanical enforcement is possible; the enforcement mechanism for each rule is listed in Section 6.22. A rule with no mechanical enforcement is enforced in code review, and a reviewer approving a violation is accountable for it.

Every convention below is stated with at least one example and one counter-example, because an example alone is ambiguous about what is excluded.

6.2 API Paths, Verbs, and Versioning #

6.2.1 Path Construction #

The one exception to "no verbs in paths": an action that is not a state change of a single resource in the create/read/update/delete sense is expressed as a sub-resource named with an imperative verb, and only from this closed list: redeem, revoke, publish, unpublish, archive, restore, complete, resend, rotate. Adding a verb to this list requires the same process as adding an error code (Section 6.5.3).

6.2.2 Verb Semantics #

Additional binding rules:

1. A GET MUST NOT mutate anything, including counters, "last seen" timestamps, or analytics rows written synchronously. Analytics is emitted through the event pipeline in Section 28, never as a side effect of a read handler.
2. A second DELETE of an already-deleted resource returns 204, not 404. Delete is idempotent.
3. PUT on a nonexistent identifier returns 404. PUT never creates.
4. Any endpoint that creates or charges something MUST accept an Idempotency-Key header; see Section 6.2.5.
5. 202 Accepted responses MUST include, in data, a resource identifier the client can poll and a statusUrl string. A 202 with no way to observe completion is prohibited.

6.2.3 Required Headers #

6.2.4 Versioning Policy #

What is and is not a breaking change. This table is exhaustive and normative. If a proposed change is not listed, it is treated as breaking until an architecture decision record says otherwise.

6.2.5 Idempotency #

Endpoints that create durable state or consume a limited resource MUST require an Idempotency-Key request header containing a ULID.

Server behavior:

1. On first use, the key is stored in Redis with the request fingerprint (method, path, and a SHA-256 of the canonicalized body) and a 24-hour lifetime.
2. A repeat request with the same key and the same fingerprint returns the original stored response verbatim, including the original status code, with the header Idempotent-Replay: true.
3. A repeat with the same key and a different fingerprint returns 409 with IDEMPOTENCY_KEY_REUSED.
4. A request arriving while the original is still in flight returns 409 with IDEMPOTENCY_KEY_REUSED and retryable: true, plus Retry-After: 2.
5. A missing or malformed key on a required endpoint returns 400 with VALIDATION_FAILED and details.field set to Idempotency-Key.

6.3 The Success Envelope #

Every 2xx JSON response body has exactly two top-level keys, data and meta. No endpoint returns a bare array, a bare scalar, or an object with domain fields at the top level.

{
  "data": { "moduleKey": "bus-pass", "title": "Getting a Bus Pass" },
  "meta": {
    "requestId": "01JAVX9Q4S8B6P1M2N3K4T5Z7W",
    "serverTime": "2026-08-18T14:03:22.118Z"
  }
}

Binding rules:

1. meta MUST NOT carry domain data. If a value is about the resource, it belongs in data.
2. A collection endpoint returns the array at data, never at data.items.
3. A 204 No Content response has an empty body. It still carries the X-Request-Id header.
4. Response serialization goes through the response schema, so a field not declared in the schema is removed rather than returned. This is the primary defense against accidentally leaking an internal column.

6.4 The Error Envelope #

Every 4xx and 5xx JSON response body has exactly two top-level keys, error and meta.

{
  "error": {
    "code": "SEAT_ALREADY_ACTIVE",
    "message": "This seat code is already in use on another device.",
    "messageKey": "errors.seat.alreadyActive",
    "details": { "field": "seatCode" },
    "retryable": false
  },
  "meta": {
    "requestId": "01JAVX9Q4S8B6P1M2N3K4T5Z7W",
    "serverTime": "2026-08-18T14:03:22.118Z"
  }
}

Binding rules:

1. One producer. Exactly one error-handling plugin constructs error bodies. A route handler MUST NOT call reply.send() with a hand-built error object. Handlers throw typed errors (Section 6.17.6); the plugin serializes them.
2. No stack traces, ever, in any environment. Stack traces are logged, never returned.
3. details is bounded. It MUST NOT exceed 4 KB serialized and MUST NOT contain a seat code, a token, a transcript, or a staff email address.
4. Unknown errors collapse. Any thrown value that is not a typed application error is logged at error with its stack and returned as INTERNAL_ERROR with HTTP 500 and retryable: true. The original message is never exposed.
5. The client renders messageKey. A client that displays error.message to a learner is defective. Client code MUST resolve messageKey through the i18n catalog and fall back to the generic key errors.generic.unexpected when the key is unknown to that build.
6. Validation errors use VALIDATION_FAILED with the field list described in Section 6.12.4.
7. retryable drives client retry. TanStack Query retry predicates read retryable; they do not maintain a separate list of status codes.

6.5 The Error Code Catalogue #

This catalogue is the single authority for error codes. Every error code emitted anywhere in this specification is defined here, with its HTTP status, its retryable flag, its i18n key, and its meaning. The consolidated appendix in Section 34 is a sorted view of this catalogue and adds nothing to it. A code that does not appear here does not exist: it cannot be thrown, it cannot be listed in a route's response map, and where any other section appears to emit one, that section is corrected against this catalogue rather than the catalogue being extended to match it.

6.5.1 Catalogue Format #

Every code is declared once, in the contracts package, as a row with five properties. The complete catalogue is reproduced as an appendix in Section 34; this subsection owns the format, the rules, and the core codes.

// packages/contracts/src/errors.ts
export interface ErrorDefinition {
  /** Stable identifier. SCREAMING_SNAKE_CASE. Immutable once shipped. */
  readonly code: string;
  /** HTTP status returned with this code. Immutable once shipped. */
  readonly httpStatus: 400 | 401 | 403 | 404 | 405 | 409 | 410 | 413 | 415 | 422 | 423 | 429 | 500 | 503 | 504;
  /** Whether an identical retry after a delay could succeed. Immutable once shipped. */
  readonly retryable: boolean;
  /** i18n key the client renders. Must exist in all 14 locale catalogs. */
  readonly messageKey: string;
  /** English developer-facing sentence. May be reworded; meaning may not change. */
  readonly message: string;
  /** Zod schema for `error.details`, or `undefined` when the code carries no details. */
  readonly details?: z.ZodTypeAny;
  /** One-line meaning, used to generate the appendix in Section 34. */
  readonly meaning: string;
}

export const ERROR_CATALOGUE = {
  SEAT_ALREADY_ACTIVE: {
    code: 'SEAT_ALREADY_ACTIVE',
    httpStatus: 409,
    retryable: false,
    messageKey: 'errors.seat.alreadyActive',
    message: 'This seat code is already in use on another device.',
    details: z.object({ field: z.literal('seatCode') }),
    meaning: 'The seat is bound to a different device and has not been released.',
  },
  // …one entry per code…
} as const satisfies Record<string, ErrorDefinition>;

export type ErrorCode = keyof typeof ERROR_CATALOGUE;

ErrorCode is a union type derived from the catalogue, so referencing a code that does not exist is a compile error everywhere in the workspace, including in route response maps and in client-side switch statements.

6.5.2 Naming Rules for Codes #

6.5.3 Rules for Adding, Changing, or Removing a Code #

Adding a code. All six steps are required before the code may be thrown.

1. Add the entry to the catalogue with all required properties.
2. Add the messageKey to the English source catalog with the learner-facing text, written to the standard in Section 21.
3. Open the translation task for all 13 support languages per Section 9. Until translations land, the key resolves through the English fallback; this is acceptable for at most one release cycle.
4. Add the code to the response map of every route that can produce it.
5. Add a test that provokes the condition and asserts the code, the HTTP status, and retryable.
6. Add a row to the appendix table in Section 34. The appendix is generated from the catalogue, so this step is mechanical, but the generated file is committed and reviewed.

Changing a code. httpStatus, retryable, code, and meaning are immutable once a release containing them reaches production. Only message (the English developer sentence) and the wording behind messageKey may be revised. A change in meaning is a new code plus deprecation of the old one.

Removing a code. A code may be removed only after two consecutive releases in which it was never emitted, verified from logs. Removal is a breaking change under Section 6.2.4 if any client branches on it; in practice, since clients must have a default branch, removal is non-breaking and is done by deleting the catalogue entry and the route references in the same commit.

6.5.4 Core Error Codes #

The following codes are the core catalogue. Every one of them MUST exist at launch.

6.6 Pagination, Sorting, and Filtering #

6.6.1 Pagination Is Cursor-Based Only #

Offset pagination is prohibited everywhere, including administrative endpoints and internal tools. There is no page parameter, no offset parameter, and no total count in any response.

Response meta gains exactly two fields on every collection endpoint:

{
  "data": [ /* up to `limit` items */ ],
  "meta": {
    "requestId": "01JAVX9Q4S8B6P1M2N3K4T5Z7W",
    "serverTime": "2026-08-18T14:03:22.118Z",
    "nextCursor": "eyJ2IjoxLCJrIjoiMDE5MmY…",
    "hasMore": true
  }
}

6.6.2 Cursor Encoding #

A cursor is opaque to clients but structured on the server: base64url of a compact JSON object, signed so it cannot be forged or hand-edited into an unintended query.

// packages/contracts/src/pagination.ts
export interface CursorPayload {
  /** Cursor format version; bumped when the payload shape changes. */
  v: 1;
  /** Sort key values of the last row on the previous page, in sort order. */
  k: readonly (string | number | null)[];
  /** Primary key of the last row, always the final tiebreaker. */
  id: string;
  /** SHA-256, first 16 hex chars, of the canonicalized query shape this cursor was issued for. */
  q: string;
}

6.6.3 Sorting #

6.6.4 Filtering #

6.7 Identifier Strategy #

6.7.1 Why UUIDv7 and Not the Alternatives #

ULIDs are used for request and idempotency identifiers precisely because they are compact, case-insensitive to read aloud, and lexicographically sortable in a log file.

6.7.2 TypeScript Helpers #

These helpers live in the contracts package and are the only sanctioned way to create or validate an identifier. Direct calls to a UUID library outside this module are a lint error.

// packages/contracts/src/primitives.ts
import { z } from 'zod';
import { uuidv7 } from 'uuidv7';
import { ulid as generateUlid } from 'ulid';

/* ---------- UUIDv7 ---------- */

const UUID_V7_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;

/** A version-7 UUID in lowercase canonical form. Branded so a raw string cannot substitute. */
export const Uuid = z
  .string()
  .regex(UUID_V7_RE, 'must be a lowercase UUIDv7')
  .brand<'Uuid'>();
export type Uuid = z.infer<typeof Uuid>;

/** Creates a new time-ordered entity identifier. The only sanctioned source of primary keys. */
export function newId(): Uuid {
  return uuidv7() as Uuid;
}

/** Narrows an untrusted string to a Uuid, throwing a typed validation error if it is not one. */
export function toUuid(value: string): Uuid {
  return Uuid.parse(value);
}

/** Extracts the embedded millisecond timestamp from a UUIDv7. Useful for diagnostics only. */
export function uuidCreatedAt(id: Uuid): Date {
  const hex = id.replace(/-/g, '').slice(0, 12);
  return new Date(Number.parseInt(hex, 16));
}

/* ---------- ULID ---------- */

const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;

/** A Crockford base32 ULID, uppercase, 26 characters. */
export const Ulid = z.string().regex(ULID_RE, 'must be a ULID').brand<'Ulid'>();
export type Ulid = z.infer<typeof Ulid>;

/** Creates a request or idempotency identifier. */
export function newRequestId(): Ulid {
  return generateUlid() as Ulid;
}

/* ---------- Opaque cursor ---------- */

/** An opaque pagination cursor. Clients must never parse or construct one. */
export const Cursor = z.string().min(1).max(512).brand<'Cursor'>();
export type Cursor = z.infer<typeof Cursor>;

// apps/api/src/lib/cursor.ts — server-side encode/decode, never shipped to a browser
import { createHmac, timingSafeEqual } from 'node:crypto';
import { Cursor, type CursorPayload } from '@lv/contracts';
import { InvalidCursorError } from './errors.js';

export function encodeCursor(payload: CursorPayload, secret: string): Cursor {
  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const tag = createHmac('sha256', secret).update(body).digest('base64url').slice(0, 22);
  return `${body}.${tag}` as Cursor;
}

export function decodeCursor(raw: string, secret: string, queryFingerprint: string): CursorPayload {
  const [body, tag] = raw.split('.');
  if (!body || !tag) throw new InvalidCursorError('malformed');

  const expected = createHmac('sha256', secret).update(body).digest('base64url').slice(0, 22);
  const a = Buffer.from(tag);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) throw new InvalidCursorError('signature');

  let payload: CursorPayload;
  try {
    payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as CursorPayload;
  } catch {
    throw new InvalidCursorError('unparseable');
  }

  if (payload.v !== 1) throw new InvalidCursorError('version');
  if (payload.q !== queryFingerprint) throw new InvalidCursorError('queryMismatch');
  return payload;
}

6.8 Timestamps and Durations #

// packages/contracts/src/primitives.ts (continued)
const RFC3339_MS_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;

/** RFC 3339 UTC timestamp with exactly three fractional digits. */
export const Timestamp = z
  .string()
  .regex(RFC3339_MS_UTC, 'must be RFC 3339 UTC with milliseconds, e.g. 2026-08-18T14:03:22.118Z')
  .brand<'Timestamp'>();
export type Timestamp = z.infer<typeof Timestamp>;

/** Serializes a Date to the canonical wire format. The only sanctioned serializer. */
export function toTimestamp(date: Date): Timestamp {
  return date.toISOString() as Timestamp; // toISOString always yields exactly 3 fractional digits
}

/** A non-negative duration in whole milliseconds. */
export const DurationMs = z.number().int().nonnegative().brand<'DurationMs'>();
export type DurationMs = z.infer<typeof DurationMs>;

6.9 Naming Conventions #

6.9.1 Database #

Every example above names an object the schema in Section 7 actually defines, so a reader learning the pattern can go and look at the real thing.

On the single underscore, so that nobody restores the double one. These patterns describe the schema as it is actually written: roughly seven hundred constraint, index, and trigger identifiers, internally consistent, against the handful of rows in this table. A convention exists to describe a codebase, not to invent a second one, so where the two disagreed the pattern moved. This is not tidiness. Section 6.22 makes these patterns a blocking test that reads the information schema and asserts every name against them, and a pattern the database does not follow is a gate that fails on essentially every constraint the first time it runs. A gate that fails on everything is switched off in its first week, and the project loses the gate rather than fixing the names.

6.9.2 TypeScript #