1. Summary
SKDC is a full-stack clinic operations platform for a multi-doctor chamber. It brings doctor scheduling, appointment tokens and the live queue, patient records and vitals, cash and UPI payments, doctor revenue sharing and settlements, dashboards and finance reports into one installable progressive web app. It is live and used by the chamber's staff, and it runs self-hosted behind Cloudflare Tunnel.
2. Problem and context
Who has the problem. A doctor chamber where several doctors hold sessions in different rooms on the same day, and front-desk staff manage everything around them.
What it costs them. Patients arrive in person or call ahead, the queue order changes constantly, payments come in as cash or UPI, and each doctor's share of the fees has to be worked out and settled later. With paper registers and manual sums, staff can't see who is waiting, patients get duplicate records, and revenue sharing and payouts are slow and error-prone. Doctor fee arrangements are commercially sensitive, so not every staff member should see them.
The approach. Treat scheduling, queue, patients, payments and settlements as one connected domain, so that a booking, a payment and the matching finance entry are always consistent.
3. Users and personas
| Persona | What they need |
|---|---|
| Front-desk staff | Book patients into a doctor's session, run the live token queue, take payment, look up patient history, on a desktop or a phone |
| Clinic owner and administrators | Configure doctors, fees and revenue shares; see dashboards; reconcile and record doctor settlements; export reports |
| Doctors (indirect) | A correct queue in their session and accurate, timely settlements |
The system has four roles. Finance features and confidential share data are limited to the privileged roles.
4. Goals and non-goals
Goals
- One live view of every session's queue: who is waiting, who is being seen, who is done.
- One record per patient, found by mobile number.
- Finance that always matches operations, with history that never changes when fees change later.
- Field-level privacy for commercial terms.
- Simple, reliable self-hosting that a small clinic can afford.
Non-goals
- Electronic medical records, prescriptions or clinical decision support.
- Online patient self-booking.
- Fully offline operation. Assumption: not needed today; the sync layer is a foundation for it (see section 9).
5. Requirements
Functional requirements
Q-1. Book into a session. As front-desk staff, I want to book a patient into a doctor's session and get the next token automatically.
- Booking finds the patient by normalised Indian mobile number, or creates or updates the profile.
- Bookings record their source (phone or in person) and type (paid consultation or zero-fee report consultation).
- Payment can be taken immediately or later, in cash or UPI.
Q-2. Run the live queue. As front-desk staff, I want to move patients through pending, in consultation, completed, cancelled and no-show.
- Only one patient can be in consultation per doctor session at a time.
- Waiting patients can be reordered; active and completed tokens can't be moved.
P-1. Patient records. As staff, I want to search patients by mobile number or name and see their visit history.
- Profiles hold contact details, age, gender, address, weight and blood pressure.
- Duplicate mobile identities are prevented.
D-1. Doctors and sessions. As an administrator, I want to manage doctor profiles and schedule many sessions across many dates.
- Each doctor has a fee and a chamber share, set as a percentage or a fixed amount.
- Sessions have a time range, room number, display order and status.
- Only privileged roles can change doctor configuration.
F-1. Finance ledger. As the owner, I want each paid consultation to create a finance entry automatically.
- The fee, chamber share and doctor share are snapshotted at booking time, so later changes don't rewrite history.
- All money is calculated in integer paise.
- Summaries cover gross revenue, cash and UPI, chamber revenue, doctor payable, settled and outstanding, for all doctors or one, over any date range.
F-2. Settlements. As the owner, I want to record doctor payouts with method, reference note, who recorded it and when.
F-3. Exports. As the owner, I want to export filtered ledgers as CSV, Excel and PDF.
R-1. Dashboards. As the owner, I want daily, weekly, monthly and year-to-date views of consultations, unique and new patients, sessions held, bookings, no-shows and cancellations, and the busiest doctors.
A-1. Sign-in. As a user, I want to sign in with a password or a passkey.
- Sessions last at most 30 days and can be revoked; passkeys can be listed and revoked.
Non-functional requirements
| Area | Requirement |
|---|---|
| Security | scrypt password hashing with per-password salts and timing-safe comparison; only hashed session tokens stored; Secure, HttpOnly, SameSite cookies; WebAuthn challenges bound to user and purpose; login rate limit; CORS allowlist; no-store API responses; production refuses to start without its secrets |
| Privacy | Role checks on every route, plus confidential share fields stripped when objects are serialised, including in sync responses |
| Auditability | Authentication events logged with user, IP, user agent and time; an append-only change log records domain changes |
| Data integrity | Multi-step operations run in one transaction, with savepoints for nested calls; constraints and foreign keys in the schema |
| Devices | Responsive layout with desktop navigation and mobile bottom navigation; installable PWA with update prompts and online/offline status |
| Operations | Loopback-only binding behind Cloudflare Tunnel; dedicated low-privilege user with systemd sandboxing and restart on failure; database-aware health check; graceful shutdown; online SQLite backups |
6. Solution overview and architecture
- Monorepo with three npm workspaces:
apps/web(React PWA),apps/server(Fastify API, services, schema, tests, ops scripts) andpackages/shared(domain types, roles, statuses, Indian locale helpers, mobile normalisation, currency maths). - Stack: TypeScript, React 19, React Router 7, Tailwind CSS 4, Lucide, Vite 8 with Vite PWA/Workbox, Dexie, Fastify 5, Zod, SimpleWebAuthn, SQLite through
node:sqlite, ExcelJS, PDFKit, Vitest, systemd, Cloudflare Tunnel. - Scale of the codebase: about 11,000 lines of TypeScript and TSX across 58 source files, 47 API route handlers, 12 relational tables.
- Delta sync: every important change writes to a monotonic change log. Clients ask for changes after their last cursor, receive upserts and deletion tombstones filtered by role, and apply them in one IndexedDB transaction. Today this is a server-to-browser cache; writes still go through the API.
7. AI design
SKDC does not use AI. Scheduling, queue rules and accounting are deterministic, which suits money and patient records.
8. Success metrics
Confirmed
- Live and used by the chamber's staff.
- Monorepo production build passing, and 11 authentication and authorisation test scenarios passing (verified 3 September 2026).
Metrics to track
- Consultations completed per day and per doctor
- Average wait from booking to consultation
- No-show and cancellation rate
- Share of paid consultations with payment recorded the same day
- Time to reconcile a doctor settlement
- Outstanding doctor payable at month end
9. Release history and roadmap
| When | Release |
|---|---|
| Go-live | Live with scheduling, queue, patients, payments, finance, settlements, dashboards, exports, passwords and passkeys |
| 3 Sep 2026 | Repository verification: build and auth test suite passing |
Next milestones
- Integration tests for appointments, finance, sync, reporting and rollback.
- Browser end-to-end tests for the full reception and settlement journeys.
- Numbered, reversible database migrations in place of runtime schema changes.
- Scheduled encrypted backups, automated restore drills and health alerts.
- CSRF protection and a formal security-header policy.
- Split the largest frontend pages into smaller components and hooks.
- Connect the IndexedDB cache to read paths and add an outbound write queue if fully offline use becomes a requirement.
10. Risks and open questions
Risks
- Test coverage. Automated tests cover authentication and authorisation only so far; booking and finance flows rely on transactions and constraints until integration tests land.
- Backups. Backup tooling exists, but scheduling and restore drills aren't automated yet.
- Single server. SQLite on one server keeps operations simple; a move to a client-server database would be needed only if measured load demands it.
11. My role
Assumption: Amar designed and built SKDC end to end: discovery with the chamber, the domain model, interaction design, frontend, API, business rules, security, reporting, tests and the self-hosted production deployment.