AfyaTrack

Ending ‘out of stock’ mysteries.

Comment

Inspiration

Kenya's public hospitals face a persistent crisis: essential medicines run out, yet the same drugs are available at inflated prices, from private suppliers. This isn't a supply problem, it's a visibility problem. No tool existed to flag, in real time, when a facility was over-relying on private procurement instead of the government's KEMSA (Kenya Medical Supplies Authority) pipeline.

I built AfyaTrack to answer one question: "Is this hospital buying drugs it should be getting for free?"

What I Learned

  • How to design a REST API in Go using the Gin framework from scratch
  • Working with PostgreSQL for real-time inventory tracking with correlated subqueries
  • The importance of input validation - a single unchecked source field could silently corrupt every insight the system produces
  • How subtle bugs (a typo like drug_namenil, a missing defer rows.Close(), division by zero on an empty database) can undermine a system that looks correct on the surface
  • That counting entries instead of quantities is a classic analytics bug - one bulk KEMSA delivery would be undercounted against many small private purchases

How I Built It

AfyaTrack is a Go REST API backed by PostgreSQL. Hospital staff (or an integrated system) POST stock entries tagged as either KEMSA or PRIVATE, along with quantity and unit price. The system tracks dispensations separately and computes available stock dynamically.

The core insight engine computes the private supplier ratio:

$$\text{Private Ratio} = \frac{\sum \text{quantity}{PRIVATE}}{\sum \text{quantity}{total}}$$

When this ratio exceeds 40%, the system fires an alert. The threshold is based on the assumption that KEMSA should be covering the majority of essential medicine supply, a facility routinely above 40% private procurement is a red flag for either KEMSA delivery failure or deliberate diversion.

Price benchmarking runs in parallel, unit prices are checked against known KEMSA reference prices, and any price exceeding 1.5× the KEMSA rate is flagged:

$$\text{High Price} = P_{supplied} > 1.5 \times P_{KEMSA}$$

Architecture

The stack is intentionally lean: Go + Gin + PostgreSQL. No ORM, no unnecessary abstraction - just direct SQL queries that are easy to audit and extend. Input validation enforces that source is strictly KEMSA or PRIVATE so no bad data silently corrupts the insights layer.

What it does

AfyaTrack is a real-time drug supply tracking API for Kenyan public hospitals. It:

  • Logs every stock entry and tags it as either KEMSA (public) or PRIVATE
  • Tracks dispensations so available stock is always accurate
  • Computes a private supplier ratio and fires an alert when over 40% of supply is coming from private sources
  • Benchmarks unit prices against KEMSA reference rates and flags any drug procured at more than 1.5× the government price

Challenges I ran into

Silent failures in Go's database layer. The database/sql package does not panic when you ignore errors from rows.Scan() - it just returns zero values. The API would respond with 200 OK and empty or wrong data, making these bugs nearly invisible without disciplined error handling at every layer.

A typo that broke stock calculations. The GetStock query referenced s.drug_namenil instead of s.drug_name in the correlated subquery - meaning dispensations were never subtracted from stock, and available quantities were always overstated.

Counting entries instead of quantities. The first version of the insights query used COUNT(*) instead of SUM(quantity). A hospital receiving one bulk KEMSA shipment of 1,000 units and two small private invoices of 10 units each would be reported as 67% private reliance - the exact opposite of reality.

Division by zero on a fresh database. Before any stock is entered, total = 0 caused a runtime panic in the ratio calculation. A simple guard fixed it, but it was a reminder that edge cases matter in systems meant to run in real hospitals.

Windows development friction. PowerShell's JSON escaping and UTF-8 BOM characters silently corrupting API request bodies cost significant debugging time before the root cause was identified.

Accomplishments that I am proud of

  • Built a working API from scratch in Go with no prior Gin experience
  • The private supplier alert fired correctly on the first real test - 44% private ratio detected and flagged as expected
  • Caught and fixed six distinct bugs during code review before they could cause silent data corruption in a real deployment
  • Designed a data model that correctly distinguishes supply volume from number of transactions - a distinction that matters enormously for accurate procurement analysis
  • The system is stateless and queryable - it can be integrated into any existing hospital dashboard or audit tool with no changes

What's next for AfyaTrack

  • Per-hospital insights - break down the private ratio by hospital_id so health authorities can identify which specific facilities are most at risk
  • Drug-level alerts - flag when a specific essential medicine like Amoxicillin or Paracetamol is being sourced privately more than others, indicating targeted diversion
  • Time-series tracking - store ratio snapshots over time so auditors can see a facility trending toward private dependence before it becomes critical
  • KEMSA price database - move reference prices from a hardcoded map into a live database table updated from KEMSA's published price lists
  • Alert history and audit log - every time the 40% threshold is crossed, log it with a timestamp so there is a permanent, tamper-evident record
  • Web dashboard - a simple frontend for hospital administrators to log stock and see alerts without needing to call the API directly
  • SMS notifications -integrate Africa's Talking API to push alerts to hospital administrators and county health officers via SMS, since reliable internet access cannot be assumed in all facilities

Built With

Share this project:

Updates