Next.js Web Portals
Relevant source files
The following files were used as context for generating this wiki page:
The Next.js web application (apps/web) provides the primary user interface for patients, clinic staff, and platform administrators. It operates as a set of distinct portals within a single Next.js project, sharing common styling, i18n strings, and business logic from the monorepo packages.
The application communicates with a Fastify-based modular monolith API (apps/api) using a typed fetch client and shared Zod contracts. It supports multi-tenancy with Postgres row-level security and follows a clinical safety rule catalogue.
Sources: README.md:9-11, README.md:20-20, apps/web/package.json:20-25
Portal Architecture
The web application divides functionality into four specific routes, each targeting a different user persona.
| Portal | Route | Primary User | Purpose |
|---|---|---|---|
| Public Site | / | Anonymous | General information and booking entry point. |
| Patient Portal | /app | Patients | Appointment booking, medical records, and prescriptions. |
| Clinic Dashboard | /clinic | Staff | Patient management, queue handling, and clinical documentation. |
| Platform Console | /platform | Admins | System-wide configuration and monitoring. |
| Waiting Room | /display | Patients | Public-facing queue status and token announcements. |
Sources: README.md:20-20, apps/web/package.json:3-5, apps/web/app/(public)/page.tsx:5-20
Portal Routing and Navigation
The following diagram illustrates the high-level routing structure within the Next.js app directory.
The application uses file-based routing where specific layouts govern each portal's look and feel.
Sources: README.md:20-20, apps/web/app/clinic/page.tsx:64-75
Clinic Portal Features
The Clinic Portal is the most complex module, handling front-desk operations and clinical workflows.
Patient Management
Staff members perform patient searches by name, phone, or UHID. The system implements a duplicate check during registration to prevent redundant records.
- Registration: Front desk assigns a Unique Health ID (UHID) based on clinic settings.
- Tagging: Staff categorize patients (e.g., "Emergency", "VIP") using color-coded tags to influence queue priority.
- Family Linking: The system links patients sharing the same phone number or guardian.
Sources: apps/web/app/clinic/page.tsx:47-59, apps/web/app/clinic/patients/new/page.tsx:75-95
Clinical Consultations
Doctors use a dedicated interface for documenting patient visits. This interface includes vitals tracking, clinical notes, and ICD-10 diagnosis search.
- Autosave: Notes save automatically after 1200ms of inactivity.
- Concurrency Control: A revision counter prevents overwriting data if the doctor has multiple tabs open or if a save is stale.
- Prescription Locking: The record locks once signed, preventing further edits to vitals or notes.
Availability and Scheduling
Doctors and administrators manage weekly schedules and exceptions (holidays/leave).
- Weekly Schedule: Defined by start/end times per weekday.
- Versions: Schedules are versioned with an "effective from" date to allow planning future changes.
- Slot Generation: The system calculates available slots based on
slotMinutesandbufferMinutes.
Sources: apps/web/app/clinic/availability/page.tsx:39-65, apps/web/app/clinic/availability/schedule-card.tsx:66-90
Administrative Workflows
Staff Invitation and Onboarding
Clinic administrators invite new staff via email or identifier. The invitation process involves a multi-step security flow.
- Invite Generation: Admin creates an invite link.
- Password Setup: User sets a new password.
- MFA Registration: User scans a QR code to set up a TOTP authenticator.
- Verification: User provides the first 6-digit code to finalize the account.
Practice Configuration
Administrators configure clinics and consultation types.
- Consultation Types: Defines the mode (In-person, Video, Audio), duration, and fees.
- UHID Settings: Configures the clinic-specific prefix and the starting number for patient IDs.
- Booking Rules: Sets the scheduling horizon (e.g., 30 days) and same-day cut-off times.
Sources: apps/web/app/clinic/practice-card.tsx:75-125, apps/api/test/patients.int.test.ts:40-45
Technical Implementation Details
Dependencies and Shared Code
The web portal leverages the monorepo structure to ensure type safety across the stack.
| Package | Usage in apps/web |
|---|---|
@dhc/api-client | Provides the request function for typed API calls. |
@dhc/contracts | Contains Zod schemas for all API responses and bodies. |
@dhc/domain | Shared logic for date formatting (IST) and currency (paise). |
@dhc/i18n | Internationalization strings for English and Hindi. |
@dhc/tokens | Design tokens for consistent colors and spacing. |
Sources: apps/web/package.json:15-25, README.md:25-38
State Management
Portals use React useState, useEffect, and useCallback for local state. Session management (auth tokens and user role) is handled via a useSession hook provided by a SessionProvider.
Sources: apps/web/app/clinic/page.tsx:39-45, apps/web/app/clinic/consultations/[id]/page.tsx:43-60
Summary
The Next.js Web Portals serve as the interface layer of the Digital Healthcare Platform. By segregating functionality into patient, staff, and admin portals, the system maintains clear role boundaries while utilizing a shared core of typed contracts and domain logic. The architecture emphasizes data integrity through revision-based autosaving and security via a robust staff invitation and MFA workflow.