CASCADE

The problem is no longer finding people

Nigeria notified 458,534 tuberculosis cases in 2025 against an estimated incidence of roughly 510,000. The detection gap that dominated the last decade has narrowed sharply. What has not improved is the economics.

So the binding constraint is not how many people we screen. It is which of the people we screen receive a confirmatory molecular test, given a finite number of cartridges, instrument-hours and transport runs. CASCADE answers that per facility, per day, and tracks every authorised test through to treatment or a documented reason for loss.

Its headline measure is number needed to test — how many presumptive tests it takes to confirm one case.

Three surfaces, one engine

The triage channel asks four danger questions first and stops the interview if one fires. It ends in a single action — where to go, what it costs, what will happen, what to bring — never a score.

What CASCADE deliberately does not do

This list is the product as much as the feature list is.

• It does not tell anyone they have TB, or that they do not. Only a laboratory says the first. The second sounds like good news and is not true — a deferral is an appointment, not a clearance.
• It does not read chest X-rays. Computer-aided detection products carry years of validation and regulatory clearance. CASCADE stores the image, routes it to a cleared vendor, and records their score and which vendor produced it.
• It does not use AI to decide who gets tested. The allocation model is a readable additive log-odds function, because a supervisor, an ethics committee and NAFDAC all have to be able to ask why her and not him. AI does conversational intake, register parsing and the supervisor briefing — the jobs that are genuinely hard without it.
• It does not route high-probability people to telemedicine. No video call confirms TB, and NTBLCP treatment is free and notifiable. Telehealth serves the deferred cohort and video-supported treatment.
• It does not export TB status across the mesh. A diagnosis costs people housing and work, and the far end is a consumer app a family may share a phone to use.

For the health worker using it

A tool earns trust by being clear about its job, not by claiming to do more than it does. So, plainly:

Things you can rely on

• The danger questions come first. Coughing blood, breathless at rest, chest pain, too unwell to eat or drink. A yes stops the interview immediately and sends the person for same-day care — nobody has to finish a questionnaire first.
• A red flag escalates, it never substitutes. Above the testing line it adds a clinician as well as the specimen. Below the line it overrides the deferral entirely.
• “Not sure” is a real answer. You are never forced to guess on someone's behalf, and an unsure answer is flagged for a person to check rather than silently treated as a no.
• The HIV question can be skipped, and the screen says so. Skipping it does not change where the person is sent.
• You can always see why. Select anyone in the queue and the tool shows exactly which recorded factors put them where they are. Nothing is hidden behind a score you cannot interrogate.

Where this sits on the evidence pathway

A tool that allocates diagnostic tests earns its place in stages, and saying which stage you are at is what a serious developer does. The software is built and its security model is tested against an adversarial suite. The clinical model is built and awaits refitting on Nigerian data — which is Phase 0, and is the next thing scheduled.

Operator guide

Everything needed to stand CASCADE up and run it, in order. This is the technical set-up guide, also available as a PDF. For the people who will actually use the tool day to day, see How to use it instead — regenerate it with python docs/make_guide_pdf.py whenever this page changes.

1. What you need first

   • A Supabase project, in a Nigerian or nearest-region data centre — NDPA 2023 expects data residency
   • A Netlify account connected to the repository
   • Node 20 or later, if you are building locally
   • An Anthropic API key — optional; the AI features are assistive and everything works without it
   You do not need a CAD vendor, a telehealth account or a messaging provider to get running. Add those later.

2. Set up the database

   In the Supabase SQL editor, run the three files in this order:

   db/cascade_schema.sql     tables, enums, views, seed facilities
   db/cascade_rls.sql        roles and row level security
   db/cascade_storage.sql    bucket policies (after step 3)

   All three are idempotent. Re-running is how you apply a change, so re-running must never error — if it does, that is a bug worth reporting.

   Order matters. cascade_rls.sql references tables created by the schema, and cascade_storage.sql references helpers created by the RLS file. Running them out of order produces confusing "does not exist" errors.

3. Create the storage bucket

   Storage → New bucket, named exactly cascade-documents, and not public. Then run db/cascade_storage.sql, which re-asserts the private flag, sets the 12 MB limit and the allowed types, and installs the facility-scoping policies.

   Never make this bucket public. It holds chest X-rays and laboratory results belonging to identifiable people in small communities. The SQL re-asserts public = false on every run precisely so an accidental toggle in the dashboard is undone the next time you deploy.

4. Deploy to Netlify

   netlify.toml is already configured — build command, publish directory, functions folder and redirects. Connect the repository and Netlify picks it all up.

   The landing page is served at / and the console at /app/.

   Every file must sit at the repository root. Both build entry points — index.html and app.html — plus netlify.toml and netlify/ live at the top level. The console reaches the /app/ URL through a redirect, not by living in an app/ folder: a one-file subdirectory is exactly the thing that goes missing in a zip upload, and its absence fails the build with Could not resolve entry module.
   Do not set BASE_PATH. That variable exists only for GitHub Pages project sites. Netlify serves from the domain root, and setting it will break every asset path.

5. Environment variables

   Site configuration → Environment variables. Nothing here is optional except where marked.

   Variable	Value	Notes
   NODE_VERSION	20
   VITE_SUPABASE_URL	Project URL	Public by design
   VITE_SUPABASE_ANON_KEY	Anon key	Public by design — RLS is what protects the data
   SUPABASE_URL	Same URL	Server side
   SUPABASE_ANON_KEY	Same anon key	Used to verify caller tokens
   SUPABASE_SERVICE_ROLE_KEY	Service role key	Never with a VITE_ prefix
   ALLOWED_ORIGIN	Your site URL
   ANTHROPIC_API_KEY	Your key	Optional — enables AI intake and briefing
   VITE_AI_PROXY_URL	/api/ai	Optional, with the above
   ENGINE_SHARED_SECRET	Mesh secret	Needed for the PulmIQ bridge

   The VITE_ prefix means "bake this into the browser bundle." Anything carrying it is readable by anyone who loads the page. That is correct for the URL and anon key, and catastrophic for the service role key. There is one Anthropic key, not two — ANTHROPIC_API_KEY and VITE_ANTHROPIC_API_KEY hold the same value; only the first is safe in a deployment.
   Redeploy after adding variables. Vite reads VITE_* at build time, not runtime. A variable added after a build will not appear until the next one — which looks exactly like a wrong key.

6. Create your first users

   Signing in is not enough. A user with no app_user row sees an explicit "no role assigned" screen and nothing else — which is the correct default, not a fault.

   Create the account in Supabase Auth, then insert the role. The first one must be an admin:

   insert into app_user (id, role, display_name)
   values ('<auth-user-uuid>', 'admin', 'Programme admin');

   Then the facility-scoped staff:

   insert into app_user (id, role, facility_id, display_name)
   values ('<uuid>', 'chew',
           (select id from facility where code = 'LA-PHC-001'),
           'Adebayo O.');

   Role	Scope	Cannot see
   chew	One facility	Any other facility
   facility_officer	One facility, plus cartridge allocation and closing losses	Any other facility
   lab_tech	One testing site	The assessment — no triage answers, no HIV status, no risk factors
   dots_officer	One treatment centre	The assessment
   state_officer	One state, read only	Assessments and individual documents; cannot change anything
   admin	Everything	—

   A facility-scoped role saved without a facility would silently see nothing, so the database refuses the row outright rather than creating a user who quietly cannot work.

7. Load your real facilities

   The schema seeds six placeholder facilities across Lagos and Kano so the system is usable immediately. Replace them with your own before anything real happens:

   insert into facility
     (code, name, state, lga, tier, has_genexpert, has_xray, accepts_swabs)
   values
     ('LA-PHC-014','Ikorodu PHC','Lagos','Ikorodu','phc',false,false,true)
   on conflict (code) do nothing;

   tier is one of phc, general, tertiary, lab_hub, dots_centre. Get has_genexpert right — the referral logic depends on it.

8. Day-to-day use, by role

   Community health worker

   1. Open the triage channel. Work through it with the person, one question per screen.
   2. Read them the outcome card. It gives one action, what it costs, and what to bring.
   3. If they are authorised for a test, collect the specimen and mark it in the tracker.
   4. When a result slip comes back, record it as a document. It advances the cascade automatically.
   A red flag — coughing blood, breathless at rest, chest pain, too unwell to eat or drink — stops the interview immediately and sends the person for same-day care. Above the testing line it adds a clinician as well as the specimen; below the line it overrides the deferral entirely.

   Facility officer

   1. Set today's cartridge count in the console. The authorisation line moves and the queue reorders.
   2. Check the overdue count in the tracker each morning — anything past its window needs a human today.
   3. Close anything genuinely lost, with the real reason.
   The loss reason is the most valuable field in the system. "Lost to follow-up" tells a programme manager nothing they can act on. "Could not afford transport" tells them to fund transport. Most of the reasons on that list name something a programme can pay for — which is why it is a fixed list and not a free-text box.

   Laboratory

   Work from the lab worklist: what arrived, under which voucher, what to test. Enter the result including the semi-quantitative grade and the rifampicin outcome. An invalid or error result does not close anything — a cartridge was consumed and the person still needs a test.

   DOTS officer

   Work from the DOTS worklist. Enrol confirmed cases the same day, screen the household, and start daily check-ins. Upload liver function tests during treatment; the system flags transaminases at roughly five times normal, or three times with symptoms, for a clinician to review. It never tells anyone to stop the drugs.

   State programme officer

   Read-only dashboards across your state: number needed to test, where the cascade leaks and why, time to treatment, and what is overdue. You cannot see individual triage answers or clinical documents, by design.

9. Wire CASCADE into PulmIQ

   CASCADE reaches the DoktorConnect app only through PulmIQ — it is deliberately not on Core's roster.

   CASCADE  →  PulmIQ  →  Core  →  app

   Copy integrations/pulmiq/cascadeBridge.js into the pulmiq project's functions/ folder, set CASCADE_ENGINE_URL and ENGINE_SHARED_SECRET, and add one line to the existing export handler:

   const { withCascade } = require('./cascadeBridge');
   payload = await withCascade(payload, { dcid, pseudonym });

   Four fields cross: whether an episode is open, when the next contact is due, the handoff, and whether the person has opted out. TB status, regimen, drug resistance, risk score, risk factors, HIV status and the callback number do not.

   That file is CommonJS, because Firebase functions are. It will not load inside a Vite repo whose package.json has "type": "module" — you get module is not defined in ES module scope, which surfaces as a 502.

10. Test your security

    Against a scratch database, never production:

    createdb cascade_test
    psql -d cascade_test -f db/cascade_schema.sql
    psql -d cascade_test -f db/cascade_rls.sql
    psql -d cascade_test -f db/rls_test_seed.sql
    bash db/rls_test.sh
    bash db/storage_test.sh

    The suites create a Lagos CHEW, a Kano CHEW, a lab, a DOTS officer, a state officer and an admin, then try to break the boundaries: cross-facility reads and writes, audit-trail tampering, path traversal, unauthenticated access.

    Run this after any policy change. Two real bugs have already been caught this way, and both looked like working security — one made every user see nothing, the other made the append-only audit trail impossible to append to.

11. When things break

    Symptom	Cause	Fix
    type "cascade_state" already exists	An older, non-idempotent copy of the schema	Use the current cascade_schema.sql; it guards every enum
    permission denied for schema app	Grants did not run — usually the RLS file was truncated or run out of order	Re-run cascade_rls.sql whole
    permission denied for sequence	Missing usage on a bigserial sequence	Re-run cascade_rls.sql; the grant is in it
    A save reports success but nothing changed	RLS refused it. A denied UPDATE returns zero rows, not an error	Every write must go through writeGuarded(). Never call .update() directly
    AI panels say "AI off" with a key set	Vite reads VITE_* at build time	Redeploy
    Function returns 502	CommonJS .js in an ESM repo, or a call over the 10-second ceiling	Check module syntax first; then check for a slow upstream call
    Uploads fail on a big X-ray	Bytes routed through a function	They must not be — the browser PUTs straight to storage from a signed URL
    Site-wide 404, no functions run	Files nested one folder deep in the repo	index.html, netlify.toml and netlify/ must sit at the repository root
    Could not resolve entry module "app/index.html"	A subdirectory did not survive the upload to GitHub	Already fixed — the console entry is app.html at the root. If you see this, you are on an older copy

12. Before any pilot

    None of these is optional, and none is currently done.

    • Field test with CHEWs. Every design rule in the triage channel is an untested hypothesis. This outranks everything else on the roadmap.
    • Translate. Hausa, Yoruba, Igbo, Pidgin — by clinicians, with back-translation. The question wording is the instrument; a bad translation is a bad test.
    • Phase 0 calibration. Until the model is refitted on Nigerian data, every probability on every screen is illustrative.
    • Replace the handoff log sink with a real datastore. A lost handoff is a lost patient, and logs rotate.
    • Set a retention period with NTBLCP. NDPA 2023 expects one, and TB has a long clinical tail.
    • Engage NAFDAC. This is software as a medical device.
    • Check policy performance at a realistic row count. app.sees_pseudonym() runs on every storage access.