Venus - Clinic Information System

Problem

Many clinics in Zambia still manage patient records, appointments, billing, and medical reports manually on paper. The result is a daily operational burden: misplaced files, duplicated records, inaccurate patient information, delayed access to critical medical data, and long patient waiting times while staff hunt for records. Paper-based record-keeping also makes it nearly impossible to guarantee the confidentiality of sensitive patient information, and the absence of reliable billing and inventory tracking contributes to revenue leakage and drug stock-outs.

Context

Venus was built as a third-year Computer Science group project (CS 301: Project Management, Group 36) at The Copperbelt University, under the supervision of Dr. Maybin Lengwe. The target users are small-to-medium private clinics in urban and semi-urban Zambia. Key constraints shaped the design: clinics have little or no dedicated ICT staff, no server infrastructure, intermittent connectivity and power, and non-technical users (receptionists, nurses, doctors, pharmacists) who need a system that mirrors how a real clinic actually runs. The scope was deliberately limited to outpatient services and clinic administration.

What I Built

A centralized, web-based clinic platform that digitizes the full patient journey and gives each role exactly the tools it needs:

• Patient registration and management - demographics, contact details, NRC numbers, and searchable patient records
• Appointment scheduling - calendar and list views, with check-in, completion, and cancellation
• Electronic medical records with a status-driven visit workflow: reception → nurse/vitals → doctor/diagnosis → pharmacy (optional) → billing → completed
• Billing and invoicing - automatic totals from services and medications, with cash, card, mobile money, and insurance payment methods
• A medication catalog with stock levels, user management for six roles, and a patient self-service portal ("My Health") for appointments, records, and billing
• Audit logging of every significant system action, visible to administrators

My Contribution

This was a four-person team project (Group 36, CS 301) built over eight months using Agile iterations - and I served as Group Leader and Developer, coordinating the student development team while contributing directly to the system's implementation. My hands-on work focused on three areas:

• Patient-facing functionality: Developed the patient side of the application - patient dashboards and patient access to their own medical information and records.
• Authentication and user management: Implemented user authentication and the user-management functionality, with role-based access control governing application features and data.
• Data layer: Worked with Cloud Firestore to manage application and patient data, with access controlled according to user roles.

Beyond the code, I contributed to functional testing, documentation, and the refinement of system behaviour across the implemented workflows, and supported deployment of the finished application through Firebase Hosting.

Architecture

A serverless, client-heavy architecture - no traditional backend server exists. The React SPA talks to Firebase services directly:

• Client: React 18 with Vite, Tailwind CSS, React Router (route-level protection via a ProtectedRoute wrapper), react-hook-form + zod for form validation
• Auth: Firebase Authentication with email/password, global state managed through an AuthContext that resolves each user's role before rendering protected pages
• Database: Cloud Firestore (NoSQL) - a users collection, per-patient MedicalRecords subcollections, plus Appointments, Prescriptions, Invoices, and a dedicated auditLogs collection queried across patients via collection-group queries
• Hosting: Firebase Hosting, with code-split pages loaded lazily behind Suspense skeletons to keep initial load fast

Technical Decisions

Every major choice was driven by the operating reality of small clinics:

• Serverless over self-hosted: OpenMRS, GNU Health, and Bahmni demand servers and technical staff clinics don't have. Firebase removes server management entirely while keeping real-time sync - the right cost and infrastructure fit.
• Firestore over a relational database: native real-time updates, offline-tolerant SDK, and a document model that maps cleanly onto patients and their nested visit history. Prefix search is implemented with a searchableName field and Firestore range queries, since Firestore has no full-text search.
• Status-driven workflow instead of free-form records: every visit moves through a fixed state sequence, which prevents duplicate active visits, enforces stage ordering, and makes the system testable.
• Secondary Firebase app instance for account creation: Firebase's createUserWithEmailAndPassword signs the new user in automatically - which would log the admin out. A temporary secondary app creates the account, writes the Firestore documents, then deletes itself, so admins can register staff without losing their session.
• serverTimestamp() everywhere: record timestamps come from the server, not client devices, so visit history can't be skewed by wrong device clocks.

Difficult Problem

The hardest challenge was access control. Our initial design used role-based visibility enforced at the route level - but test case TC-22 exposed the gap: any doctor could open any patient's record once on the records page. Role gating controlled which pages a user could reach, but not which specific patient records they could see. In a clinical setting that's a serious confidentiality failure - and it mirrored how real clinics work, where a doctor doesn't have blanket visibility into colleagues' patients.

Solution

We moved from role-based to assignment-based access control. Medical records are now scoped to the specific named doctor treating the patient, and handoffs between stages (reception → nurse, nurse → doctor) target a named staff member rather than broadcasting to an entire role. Each record now shows exactly which staff member handled each stage, creating clearer accountability. We treated TC-22 not as a code defect but as an incompletely specified requirement, and revised the access model accordingly - exactly the kind of change Agile iterations are designed to surface.

Evidence

• All 25 manual test cases passed - covering authentication, role restrictions, patient/staff management, the full visit workflow (TC-14 through TC-23), and form validation
• Duplicate active visits correctly blocked via getActivePatientRecord; targeted handoffs confirmed - only the named nurse sees the patient in their queue (TC-22c)
• Audit log entries verified: every create, vitals update, diagnosis, and staff registration captured with user, role, resource, and server timestamp
• Deployed and exercised end-to-end at venus-clinic-system.web.app

Result

A working, deployed clinic information system that fulfills its objectives: centralized real-time patient records, appointment scheduling, a structured multi-stage clinical workflow, billing, and secure, auditable record access - all without a single server to manage. The system passed its full test suite and was evaluated against its original objectives, with the access-control refinement standing out as evidence that testing genuinely shaped the design. It remains scoped to outpatient services, and future work includes national-system integration (SmartCare), offline resilience, and inventory tracking.

What I Learned

Technical lessons: security must be layered - route protection alone is not access control; serverless architectures trade infrastructure burden for careful data modeling and security-rule discipline; and workflow state machines make complex domain logic testable. Human lessons: requirements must be validated against real operational practice (our initial design missed a requirement real clinics would have caught immediately), and in a system handling patient data, accountability is a feature - every design decision should make it clearer who did what.

Code / Demo

Live demo · Source repository