~/projects/klinika/README.md
Klinika is client work in progress: online booking for a clinic whose secretary used to coordinate every patient by hand. Patients pick a doctor and either a fixed time slot or a numbered queue spot, and can see whether the doctor is in today. The front desk and doctors run the day from a role-based staff dashboard. The booking rules live in Postgres constraints, so two simultaneous requests cannot both win the same slot.
cat architecture.flow
architecture.flow
Patient booking
Front desk
Planned
cat problem.md
The clinic runs on a secretary who coordinates every patient by hand. There is no online booking, and patients can't tell whether their doctor is coming in today.
Booking is harder than it looks. Doctors work differently: some see patients at fixed times, others run a daily queue with a capacity. Two people booking the same slot at the same moment must never both succeed, and a cancellation must free the spot immediately.
It also handles patient contact details, so the Philippine Data Privacy Act applies. The first version stores booking data only, with no clinical notes.
cat solution.md
I built a custom Next.js and Postgres app, in phases, each verified before the next starts. Each doctor is set to either slots or queue mode. The public site shows live doctor status, and a four-step flow takes a new or returning patient from choosing a doctor to a confirmation.
Double-booking is prevented where it can't be bypassed: in the database. Partial unique indexes ignore cancelled rows, so a cancellation frees its slot at once. A row lock on the schedule keeps queue capacity and numbering from racing.
Staff get a dashboard with three roles. The secretary runs the day, doctors see and update only their own patients and status, and an admin can do everything. Every page and API call re-checks the session in the database, and sensitive actions are written to an audit log.
Messaging is deliberately not in Phase 1. The site makes no promise of reminders until SMS and Messenger actually exist.
ls ./components
Slot and queue modes per doctor, day-off exceptions, a 30-day booking window, and typed error codes. Appointment times are stored as clinic wall-clock time because it is a single-timezone clinic.
Three partial unique indexes stop a slot, a queue number, or a patient's same-day booking from being taken twice. A composite foreign key makes the database reject a queue block on a slot-mode doctor.
Mobile-first pages with a live "who is in today" card, plus a small validated JSON API with stable error codes, rate-limited lookups and security headers on every response.
Today's appointments with confirm, cancel, attended and no-show actions, doctor In, Delayed and Away status, and a call list of unconfirmed bookings. On phones, appointments render as cards, not a table.
Admin-created accounts with a temporary password that must be changed at first sign-in. Sessions are random tokens with only a hash stored, 12-hour expiry, lockout after repeated failures, and an audit log of logins and status changes.
Tests run against a real Postgres in a throwaway database, and the setup refuses to run against any other. The concurrency test was proven real by removing a guard index and watching it fail.
./run --trace
The patient picks new or returning, then a doctor, then a day.
A slot or queue spot is claimed inside a transaction. If another request got there first, the database rejects this one and the patient is shown fresh availability.
The patient gets a confirmation, with a queue number where the doctor runs a queue.
Front desk and doctors move the appointment through confirmed, attended or no-show. Cancelled is final and frees the spot.
klinika --phases
Doctors and schedules, booking site, staff dashboard, double-booking guard. Built through the day dashboard; admin screens for accounts, schedules and days off are next.
SMS reminders, one-tap confirm, reschedule or cancel links, and a call list for unconfirmed patients.
A Messenger bot for FAQs, "my appointment" lookups and doctor status. Clinical questions hand off to the secretary.
Post-visit follow-ups, waitlist, no-show tracking and reports.
tail -f incidents.log
cat package.json | jq .stack
echo $EXIT_STATUS
outcome.log
Phase 1 is running in a private staging environment with 54 passing tests and a real-browser check of the full booking journey, including no horizontal overflow on a phone-sized screen.
The project is client work in progress and not yet publicly exposed. Notifications and the Messenger bot are planned for later phases and are not claimed anywhere on the site.