Uzima Link

Uzima Link is a digital health records system designed around a real constraint in Kenyan healthcare: patient data is fragmented across paper files, phones, and disconnected systems, and consultations happen in more than one language. The platform gives facilities role-based digital records and uses an AI pipeline to turn spoken or typed clinical notes into structured, searchable entities.

Community health workers and small facilities in Kenya often keep patient history on paper or in scattered notes. When a patient moves between a kiosk, a clinic, and a specialist, none of that history travels with them, and clinicians re-collect the same information — slowing care and increasing the risk of missed context (allergies, ongoing medication, prior diagnoses).

This was built as a solo technical deep-dive to explore whether an AI extraction layer could realistically sit on top of a standard clinical records schema without adding friction for non-technical users — a question directly relevant to Dataloom's broader thesis about fragmented organizational data.

Four roles were modeled directly into the system: patients (view their own history), doctors (record consultations, review structured history), kiosk operators (register patients and intake basic data at community access points), and admins (manage facility onboarding and access).

• Give every facility role a scoped, secure view of only the data relevant to them
• Let clinicians speak or type consultation notes in natural language and have key clinical entities extracted automatically
• Support multiple languages used in everyday clinical settings, not just English
• Gate access by facility using invite codes rather than open registration, to keep patient data within trusted networks

• Choosing an entity-extraction approach that stayed accurate across mixed-language, informally structured clinical notes
• Migrating between Gemini API versions mid-build without breaking the extraction pipeline
• Correctly tagging audio uploads with an explicit mime_type — a subtle failure point that silently corrupted transcription if skipped
• Designing role-based auth so a kiosk operator's intake action, a doctor's clinical write, and a patient's read-only view all pass through the same API surface safely

The system separates concerns cleanly: FastAPI handles auth, role scoping, and CRUD against a PostgreSQL schema via SQLAlchemy; a dedicated pipeline service sends consultation input (text or transcribed audio) to the Gemini API with a structured extraction prompt, then validates and writes the returned entities (symptoms, diagnosis, medication, follow-up) back onto the patient record. Facility invite codes gate signup so new accounts are always scoped to a real, approved facility.

Next.js frontend → FastAPI service layer (auth, role middleware, CRUD routes) → PostgreSQL via SQLAlchemy ORM, with a parallel extraction path: consultation input → Gemini API (structured prompt) → validation layer → structured clinical entities written to the patient record.

Core tables: facilities, users (role enum: patient/doctor/kiosk_operator/admin), patients, consultations, and extracted_entities (typed by entity kind — symptom, diagnosis, medication, follow_up), each linked back to a consultation and patient for full audit history.

REST endpoints are scoped by role at the middleware level rather than per-route, so /patients/{id} returns different shapes depending on whether the caller is the patient, their doctor, or an admin — reducing duplicated authorization logic across endpoints.

• Role-based authentication and authorization (patient, doctor, kiosk operator, admin)
• Facility invite-code gating for account creation
• AI-assisted clinical entity extraction from consultation notes
• Multilingual note intake (text and audio)
• Structured, queryable patient history across visits and facilities

Consultation text (or transcribed audio) is sent to the Gemini API with a structured extraction prompt requesting typed clinical entities. Output is validated against an expected schema before being persisted, so malformed or incomplete model output degrades gracefully instead of corrupting the record.

Manual and scripted testing across each role's permission boundaries (verifying a kiosk operator cannot read another facility's patients, for example), plus targeted testing of the extraction pipeline against a range of note styles and both supported input languages.

JWT-based auth, role-scoped middleware, and facility-gated registration keep data access aligned to real-world trust boundaries. Patient-identifying fields are only exposed to roles that need them for care delivery.

Extraction requests are handled asynchronously so a slow AI response doesn't block the rest of the consultation-recording flow for the clinician.

This is an in-progress build rather than a deployed production system. The architecture, role model, and extraction pipeline are functional in a development environment; facility pilots and real clinical data are not yet in place. [Placeholder: replace with pilot outcomes once available.]

• API version migrations (like Gemini's) need an explicit compatibility check step, not an assumption that the interface is stable
• The most dangerous bugs in a multi-role system are the silent ones — a permission check that's missing rather than wrong is much easier to overlook
• For AI-assisted extraction to be trustworthy in a clinical context, validation of model output matters as much as the extraction itself

• Facility pilot with real (de-identified) intake data
• Offline-first support for kiosk operators in low-connectivity areas
• Clinician-facing review/edit step before extracted entities are finalized