HudumaQ

Inspiration

Kenyan citizens lose full workdays to Huduma Centre queues for a process that takes under 10 minutes. eCitizen Kenya launched appointment scheduling for national ID services, proved the demand was real, then deprecated the feature - leaving millions of people stuck in a walk-in queue that can run 6+ hours.

HudumaQ is a working answer to that gap.

What it does

Citizens book a specific time slot for Huduma Centre ID services — New ID Application, Replace Lost ID, or Collect ID — without creating an account. Enter your name, email, and ID number. A magic link arrives within seconds. Pick a time. Show up at your time and join a dedicated scheduled lane instead of the general queue. On the staff side: a live dashboard showing the day's appointments sorted by time. One click to verify a citizen's arrival and generate their appointment code. Missed slots are detected and handled automatically every 5 minutes - no staff action required.

How we built it

React 18 + Vite frontend on Vercel. Five Firebase Cloud Functions in Python 3.12 handling all business logic: verification email, slot holding via Firestore transaction, booking confirmation, arrival verification, and the scheduled missed-slot sweep. Email via Brevo. Firestore for all state. PDF appointment slips and ICS calendar files generated entirely client-side - no server round-trip. The entire app - 9 pages, 4 components, 5 Cloud Functions, email templates, Firestore security rules, and composite indexes - was built spec-first. Every page, component, and function was named, described, and specified before a single line of code was written. Build time was almost entirely execution.

Challenges we ran into

The gap between "written code" and "deployed and working." A Firebase Secret Manager misconfiguration, a conflicting .env file, and frontend changes that never got pushed to git each caused production failures that had nothing to do with the code itself. Spec-driven development gets you to correct code quickly. Deployment is its own discipline - one that deserves the same upfront planning.

Accomplishments that we're proud of

A complete, two-sided booking system — citizen flow and staff dashboard — deployed end-to-end within a hackathon window. The slot-hold race condition (two citizens hitting the same slot simultaneously, resolved via Firestore transaction) was handled correctly on the first attempt, because it was specified precisely before being built.

What we learned

Treat secrets setup as day-one infrastructure. Treat git push as the unit of "done" for frontend work. Treat deployment as a first-class checklist item — not an afterthought.

What's next for HudumaQ

Nothing dramatic. The point was to demonstrate that appointment scheduling should not be a premium service, and that citizens shouldn't have to spend six hours replacing a document.

Built With

• stack:-react-+-vite-+-tailwind-(javascript