Clarity Clinic

Clarity Clinic is a clinic appointment and booking system built as a monorepo. It comprises three apps: a Backend API (ASP.NET Core 8) that owns all business logic and data, a Patient app (React 19) for self-service booking, and a Staff dashboard (Angular 20) for admins, receptionists, and doctors.

The backend exposes a JSON/REST API secured with custom JWT authentication and role-based authorization, featuring a 15-minute slot engine, race-safe booking, an HMAC-signed payment webhook, and Accept-Language localization (English/Arabic). This page is the single reference for the whole system — read it to understand the architecture and to call every endpoint.

Clarity Clinic is a classic three-tier system: two frontend clients talk to one backend API, which persists everything in SQL Server.

The backend is layered: Controllers → Services → EF Core DbContext. Controllers are thin HTTP adapters; services hold business logic (slot engine, booking, payments); EF Core maps to SQL Server LocalDB (database ClinicDb). The API uses custom JWT auth (BCrypt password hashing, no ASP.NET Identity UI) and role-based [Authorize] attributes. Cross-cutting features include a global exception envelope, restrictive CORS (only the two known frontends), and JSON-file localization keyed off the Accept-Language header.

Tech stack

Swagger UI is served at http://localhost:5180/swagger.

All three apps run locally on the ports above. Start the backend first — it auto-migrates and seeds the database on boot.

Building a client? The must-read companion is the Frontend integration notes (docs/FRONTEND.md).

Backend API

cd backend
dotnet run --project Clinic.Api --urls http://localhost:5180

# PowerShell
$env:Clients__StaffApp = "http://localhost:4321"
dotnet run --project Clinic.Api --urls http://localhost:5180

# bash
Clients__StaffApp=http://localhost:4321 dotnet run --project Clinic.Api --urls http://localhost:5180

On boot the backend applies EF Core migrations and seeds data (see Seeded credentials) into SQL Server LocalDB (ClinicDb).

Reset the database (drops it; the next run re-migrates and re-seeds)

cd backend
dotnet ef database drop --force --project Clinic.Api
dotnet run --project Clinic.Api --urls http://localhost:5180

cd patient-app
npm install
npm run dev

cd staff-dashboard
npm install
npm start -- --port 4321

Smoke test

A scripted end-to-end check (35 assertions) against a running backend:

API_BASE=http://localhost:5180 node backend/smoke-test.mjs

The API uses JWT Bearer tokens. Passwords are hashed with BCrypt; there is no ASP.NET Identity UI.

• POST /api/auth/register — patient self-signup. Returns { token, user }.
• POST /api/auth/login — any user. Returns { token, user }.

Send the token on every authenticated request:

Authorization: Bearer <token>

Optionally set Accept-Language: en or Accept-Language: ar to localize response messages.

Response shape

Both register and login return { token, user }, where user is:

{
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "role": "Patient | Doctor | Receptionist | Admin",
  "isActive": true,
  "avatarUrl": "string | null"
}

Example — log in and capture the token

# Log in as the seeded patient and store the JWT in $TOKEN
TOKEN=$(curl -s -X POST http://localhost:5180/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{ "email": "patient@clinic.local", "password": "Pat#123" }' \
  | python -c "import sys, json; print(json.load(sys.stdin)['token'])")

echo "$TOKEN"

# Use it
curl -s http://localhost:5180/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

There are four roles (the UserRole enum): Patient, Doctor, Receptionist, Admin. Permissions are enforced server-side via [Authorize(Roles = ...)]; the UI only hides controls. Anonymous endpoints (browse doctors/services, payment webhook) need no token.

* Payment endpoints are AllowAnonymous (the gateway calls them), so any caller may reach them.

An appointment moves through the AppointmentStatus enum. The path depends on how it was booked.

• Online + paymentMethod Online → PendingPayment; after payment → Confirmed.
• InClinic + Cash → Confirmed immediately (the patient pays at the clinic; reception later marks it cash-paid).
• Confirmed → Arrived (reception checks the patient in) → Completed (the doctor completes the visit and writes diagnosis/prescription).
• Confirmed or Arrived → NoShow (reception).
• Confirmed or PendingPayment → Cancelled (patient or reception). The slot is freed and can be rebooked.

Availability is computed on a 15-minute grid. Given a doctor, a date, and a service, the engine returns the start times at which an appointment of that service's duration fits without overlapping existing bookings.

• Slots are 15-minute increments ("09:00", "09:15", "09:30", ...).
• Duration-fit: a slot is only offered if the full service duration fits inside the doctor's working window for that day.
• Overlap-safe: slots that would collide with existing active appointments are excluded.
• The doctor's working days are Sunday–Thursday (per seed data); blocked dates and availability windows further constrain results.

Fetch open slots

curl -s "http://localhost:5180/api/doctors/1/slots?date=2026-06-21&serviceId=1"
# → { "date": "2026-06-21", "slots": ["09:00","09:15","09:30", ...] }

Two booking paths determine whether a payment is required.

• Online + Online payment → appointment is created as PendingPayment and the booking response includes a payment object with a checkoutUrl. After payment is confirmed, the appointment becomes Confirmed.
• InClinic + Cash → appointment is created as Confirmed immediately, payment is null. Reception later marks it cash-paid via PUT /api/appointments/{id}/cash-paid.

Two payment endpoints (both AllowAnonymous):

• POST /api/payments/webhook — the real, production gateway callback. It is HMAC-signed: the gateway sends the signature in the X-Signature header, with body { transactionRef, status }. The handler is idempotent.
• POST /api/payments/mock/pay — a dev-only helper that simulates the gateway: it signs the payload server-side and drives the same signed, idempotent webhook handler, marking the appointment Paid → Confirmed. Body { appointmentId, status? } (status defaults to "Paid"). Idempotent — calling it twice leaves the appointment Paid once. Returns { "paid": <bool> }.

User-facing API messages are localized from JSON resource files (Resources/en.json, Resources/ar.json) resolved from the request's Accept-Language header. Send Accept-Language: en or Accept-Language: ar:

curl -s -X POST http://localhost:5180/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept-Language: ar" \
  -d '{ "email": "nope@x.com", "password": "wrong" }'

The frontends mirror these keys (react-i18next / Angular), and an interceptor sends Accept-Language so backend messages return in the active language.

Every error is returned with the matching HTTP status code and a consistent JSON envelope.

{
  "error": "validation",
  "message": "Human-readable, localized message.",
  "details": ["optional", "field-level", "messages"]
}

Four real journeys through the system. Set up the base URL once; each flow logs in to get its own token.

export baseUrl=http://localhost:5180

# 1) Log in as the patient
TOKEN=$(curl -s -X POST $baseUrl/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "patient@clinic.local", "password": "Pat#123" }' \
  | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

# 2) Find an open slot (doctor 1, service 1 = General Consultation)
curl -s "$baseUrl/api/doctors/1/slots?date=2026-06-21&serviceId=1"

# 3) Book ONLINE with ONLINE payment → PendingPayment, payment.checkoutUrl returned
curl -s -X POST $baseUrl/api/appointments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "doctorId": 1,
        "serviceId": 1,
        "date": "2026-06-21",
        "startTime": "09:00",
        "mode": "Online",
        "paymentMethod": "Online"
      }'
# → 201 { "appointment": { "id": 10, "status": "PendingPayment", "meetingLink": "...", "endTime": "09:30", ... },
#          "payment": { "id": 5, "checkoutUrl": "https://gateway/checkout/..." } }

# 4) Simulate payment (dev) → appointment becomes Confirmed
curl -s -X POST $baseUrl/api/payments/mock/pay \
  -H "Content-Type: application/json" \
  -d '{ "appointmentId": 10 }'
# → { "paid": true }

# 5) Confirm
curl -s "$baseUrl/api/appointments/10" -H "Authorization: Bearer $TOKEN"
# → appointment.status == "Confirmed"

TOKEN=$(curl -s -X POST $baseUrl/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "patient@clinic.local", "password": "Pat#123" }' \
  | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

# Book IN-CLINIC with CASH → Confirmed immediately, payment is null
curl -s -X POST $baseUrl/api/appointments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "doctorId": 1,
        "serviceId": 2,
        "date": "2026-06-21",
        "startTime": "10:00",
        "mode": "InClinic",
        "paymentMethod": "Cash"
      }'
# → 201 { "appointment": { "status": "Confirmed", ... }, "payment": null }

RTOKEN=$(curl -s -X POST $baseUrl/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "reception@clinic.local", "password": "Recep#123" }' \
  | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

# Walk-in for a brand-new patient (or pass "patientId" for an existing one)
curl -s -X POST $baseUrl/api/appointments/walk-in \
  -H "Authorization: Bearer $RTOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "newPatient": { "name": "Sara Nabil", "phone": "+201000000000", "email": "sara@example.com" },
        "doctorId": 1,
        "serviceId": 1,
        "date": "2026-06-21",
        "startTime": "11:00",
        "mode": "InClinic"
      }'

# Reception logs in and checks the patient in (appt id 10, Confirmed → Arrived)
RTOKEN=$(curl -s -X POST $baseUrl/api/auth/login -H "Content-Type: application/json" \
  -d '{ "email": "reception@clinic.local", "password": "Recep#123" }' \
  | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

curl -s -X PUT $baseUrl/api/appointments/10/arrived -H "Authorization: Bearer $RTOKEN"

# Doctor logs in, records the visit (diagnosis + prescription), then completes
DTOKEN=$(curl -s -X POST $baseUrl/api/auth/login -H "Content-Type: application/json" \
  -d '{ "email": "doctor@clinic.local", "password": "Doc#123" }' \
  | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

curl -s -X POST $baseUrl/api/appointments/10/visit \
  -H "Authorization: Bearer $DTOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "diagnosis": "Seasonal allergic rhinitis",
        "notes": "Advise antihistamines; review in 2 weeks.",
        "prescription": [
          { "drug": "Loratadine", "dosage": "10mg once daily", "duration": "14 days" }
        ]
      }'

curl -s -X PUT $baseUrl/api/appointments/10/complete -H "Authorization: Bearer $DTOKEN"

# Patient logs in and views their prescriptions
PTOKEN=$(curl -s -X POST $baseUrl/api/auth/login -H "Content-Type: application/json" \
  -d '{ "email": "patient@clinic.local", "password": "Pat#123" }' \
  | python -c "import sys,json;print(json.load(sys.stdin)['token'])")

curl -s $baseUrl/api/me/prescriptions -H "Authorization: Bearer $PTOKEN"

{{baseUrl}} = http://localhost:5180. Authenticated calls send Authorization: Bearer $TOKEN. All requests/responses are JSON. Add Accept-Language: en|ar to localize messages.

These are the non-obvious behaviours that trip people up. All verified against the live API.

1. Only POST /api/appointments wraps its response. Booking returns { appointment, payment }. Every other appointment endpoint — walk-in, GET /appointments/{id}, cancel, reschedule, arrived, no-show, cash-paid, complete — returns the AppointmentDto directly (no appointment/payment wrapper). Don't reach for .appointment on those.
2. Online vs. cash booking differ: mode: Online + paymentMethod: Online → 201 PendingPayment with payment.checkoutUrl and a meetingLink; mode: InClinic + paymentMethod: Cash → 201 Confirmed with payment: null (paid at the desk → reception calls cash-paid later).
3. Slots respect service duration, not just the 15-min grid. A slot is only offered if the whole service fits without overlap. Booking a 30-min service at 09:00 removes both 09:00 and 09:15 from availability. Past times for today are filtered out; days off (Fri/Sat) and blocked dates return zero slots.
4. Always re-fetch slots after a booking, and handle 409 ("that slot was just taken") by re-fetching and asking the user to re-pick. Double-booking is race-safe on the server.
5. A newly admin-added doctor has no services. POST /api/admin/doctors creates the login + availability but not bookable services — create them via POST /api/services before that doctor can be booked.
6. Numeric fields accept a number or a numeric string. serviceId: 1 and serviceId: "1" both work (ASP.NET Web JSON defaults). Send real numbers from typed code.
7. GET /api/doctors pages at pageSize=10 by default. Pass pageSize (and page) if you need more than 10 per request. Filters available: search, specialization, serviceId, availableOn, mode.
8. Errors are a consistent envelope: { error, message, details } with the correct HTTP status — 400 validation, 401 no/invalid token, 403 wrong role, 404 not found, 409 conflict (slot taken or a business rule like deactivating a doctor who has future appointments). Surface message to users.

A ready-to-import Postman collection is provided so you can exercise every endpoint without writing curl.

Import the collection (and its environment, if present), set the baseUrl variable to http://localhost:5180, log in to capture a token, and run the requests. Most authenticated requests reference the captured token via the Authorization: Bearer {{token}} header.

On boot the backend seeds these accounts (passwords are for local development only).