π© Exam-Type Feature Flags
LinguFlow gates each certification exam type (TOEIC, IELTS, HSK, JLPT, and future additions like TOEFL or TOPIK) behind a backend-owned enable/disable flag. This gives operators two things without a redeploy: content-readiness gating (keep a newly-seeded exam type hidden until it's verified) and an ops kill switch (instantly hide a broken exam type). It is a global on/off per type, not per-user targeting or A/B experimentation.
ποΈ Data Modelβ
A dedicated exam_type_flags table, added in migration 0006_exam_type_flags:
| Column | Type | Notes |
|---|---|---|
exam_type | VARCHAR (Primary Key) | "toeic", "ielts", "hsk", "jlpt", ... |
enabled | BOOLEAN (default true) | |
label | VARCHAR | Display name, e.g. "TOEIC" |
updated_at | TIMESTAMPTZ |
Absence means enabled, not disabled. A type with no row in this table β including
custom (user-created exam templates), which is never represented here β is treated
as enabled. Only an explicit enabled = false row disables a type. This rule holds
end-to-end: the backend service, the API response, and the frontend catalog all apply
it the same way, so a not-yet-seeded exam type never accidentally disappears.
π APIβ
| Method | Endpoint | Description | Protected |
|---|---|---|---|
GET | /api/exam-types | Enabled/disabled state for every flag-controlled exam type | No |
Response:
[
{ "key": "toeic", "enabled": true },
{ "key": "hsk", "enabled": false }
]
No auth is required β this is global configuration, not user data, and the exam hub needs it before a viewer is necessarily logged in.
π¦ Enforcementβ
Assessment routers enforce the flag:
GET /api/examsexcludes any exam whoseexam_typeis disabled, in addition to ownership / visibility filtering.POST /api/attempts,POST /api/practice/from-exam, andPOST /api/practice/from-bank(when a filter carriesexamType) return 403 (not 404) when the type is disabled. 403 rather than 404 is deliberate: unlike a private exam, there is nothing sensitive to hide about a type being temporarily unavailable.
An attempt already in progress or completed is never affected. Disabling a type
only blocks new starts and hides the type from listings β answering, viewing
results, and finishing an already-started attempt on a since-disabled type all keep
working. Results resolve from pinned attempt_items / responses / scores, not
the live exam catalog.
π₯οΈ Frontendβ
frontend/src/shared/examTypes.tsβEXAM_TYPE_CATALOG, the single canonical list of known exam-type keys, plusfilterEnabledCatalog(), a pure function that intersects the catalog with the backend's enabled/disabled response.frontend/src/shared/store/examTypeFlagsStore.tsβ a Pinia store that fetchesGET /api/exam-typesonce (ensureLoaded()) and exposes the result asenabledTypes. On a failed fetch it falls back to treating every type as enabled, so a broken flags endpoint never takes down exam browsing entirely.
The exam hub, exam composer, and question bank (filters and the question form) all read from this one store instead of hardcoding the exam-type list β adding a new exam type no longer means hunting down multiple hardcoded arrays.
π οΈ Operator Guideβ
There is no admin UI for toggling flags by design (see below) β it's a direct database write:
-- Disable an exam type (kill switch)
UPDATE exam_type_flags SET enabled = false, updated_at = now() WHERE exam_type = 'hsk';
-- Re-enable it
UPDATE exam_type_flags SET enabled = true, updated_at = now() WHERE exam_type = 'hsk';
Launching a brand-new exam type (e.g. TOEFL):
- Add its seed content under
backend/app/seed/data/(seetoeic_reading.pyfor the pattern), withexam_type="toefl". - Insert a row with
enabled = false:INSERT INTO exam_type_flags (exam_type, enabled, label, updated_at)VALUES ('toefl', false, 'TOEFL', now()); - Add one entry to
EXAM_TYPE_CATALOGon the frontend. - Verify the seeded content in a local/staging environment β a disabled type is invisible to everyone, with no bypass, so verification happens where you control the flag directly rather than in production.
- Flip
enabled = truein production. No redeploy, no new components.
π§ Why Not Vercel Feature Flags?β
LinguFlow's frontend is a static Vite SPA on Vercel that only rewrites /api/* to
the Railway backend β there's no Vercel-side server component in the request path to
evaluate flags against, which is the actual value proposition of Vercel's flag
tooling. The backend also has to be the enforcement authority regardless (the API
must reject a disabled type even if the UI is bypassed), so a backend-owned table
avoids maintaining a second, redundant source of truth across two platforms.