How athulmb/clinic-management works
This repository is a Next.js front-end application for a clinic/healthcare operations platform. The architecture is centered on the Next.js App Router, with domain-specific screens under src/app, reusable UI building blocks under src/components, and global client state managed through Redux slices, React contexts, and a small set of shared services.
1) Top-level architectural shape
The app is organized as a multi-module clinic management system rather than a single-purpose site. The major functional areas visible in the route tree are:
• authentication and onboarding
• registration setup
• patients
• doctors
• bookings
• messages
• HR
• accounts/finance
• analytics
• settings
• profile and dashboard/home pages
This suggests a single SPA-like product experience built with Next.js server/client components, but the actual domain logic is mostly client-side and component-driven.
2) Routing and page composition
src/app contains the application routes. Most folders map directly to user-facing modules:
• src/app/login, forgot-password, reset-password, register, settings, profile
• src/app/patients, src/app/doctors, src/app/bookings, src/app/messages
• src/app/hr, src/app/accounts, src/app/analytics
There are several important route patterns:
• Route groups for auth flow: src/app/(auth)/onboarding
• Dynamic detail routes:
- src/app/doctors/[id]
- src/app/patients/[id]
- src/app/patient-365/[id]
• Nested workflow routes:
- src/app/bookings/new
- src/app/patients/[id]/transfer
- src/app/register/admin, licensing, location, terms
This indicates the UI is structured around discrete workflows and entity detail pages, with dynamic routes for per-record views and nested pages for guided flows.
3) Layout and shell architecture
The app has multiple layout layers:
• src/app/layout.tsx is the root application shell
• src/app/hr/layout.tsx is a section-specific HR shell
• src/app/settings/layout.tsx is a section-specific settings shell
At the component level, the shell is composed from shared navigation and chrome elements:
• src/components/organisms/sidebar.tsx plus sidebar/sidebar-navigation.tsx and sidebar/sidebar-footer.tsx
• src/components/organisms/top-nav.tsx
These components strongly suggest a dashboard layout pattern where a persistent sidebar and top bar frame the module pages.
4) Presentation-layer organization
The component hierarchy is intentionally layered:
Atoms
src/components/atoms
• lowest-level form and profile elements
• examples: form-elements.tsx, profile-atoms.tsx
Molecules
src/components/molecules
• small composed UI pieces like logo, calendar, pagination, cards
• examples: action-card.tsx, mini-calendar.tsx, notched-card.tsx, session-item.tsx
Organisms
src/components/organisms
• large feature-oriented composites
• examples by domain:
- bookings: booking form, wizard, table, search, modals
- doctors: cards, search, add-doctor modal
- patients: add/edit/detail modals and forms
- messages: chat area, header, input, list, video call
- HR: staff, leave, package, allowance, salary modals
- accounts: settlement modal
- home: home dashboard components
This is a clear design-system-plus-feature-components structure. The components/ui folder contains low-level primitives such as button, card, input, avatar, checkbox, tooltip, etc., which likely act as the foundational design system. The presence of components.json also suggests a shadcn/ui-style setup.
5) Domain subsystems
Patients
Patients are a first-class domain with:
• list page: src/app/patients/page.tsx
• detail pages: src/app/patients/[id]/page.tsx
• add workflow: src/app/patients/add
• verify page: src/app/patients/verify
• transfer workflow: src/app/patients/[id]/transfer
Supporting components include add/edit modals and form sections under src/components/organisms/patients, plus typed state in src/features/patients/patientSlice.ts and patientTypes.ts.
Doctors
Doctors have:
• list page: src/app/doctors/page.tsx
• dynamic profile page: src/app/doctors/[id]/page.tsx
There is a fairly rich subcomponent structure for the detail page:
• profile header
• overview tab
• patients tab
• schedule tab
• stats grid
There are also multiple data files in src/app/doctors/, which suggests the current UI may be seeded with local/static datasets or mock data.
Bookings
Bookings are modeled as a workflow-heavy module:
• list page: src/app/bookings/page.tsx
• new booking flow: src/app/bookings/new/page.tsx
The supporting components indicate a multi-step wizard architecture:
• patient selector
• doctor selector
• session type selector
• pricing utilities
• booking form, search, table, stats, details modal
• wizard steps under wizard-steps/
This is likely one of the most complex UI flows in the repo, with local step state, selection state, and booking pricing logic all encapsulated in feature components.
Messages
Messaging is another major subsystem:
• page: src/app/messages/page.tsx
• data model and types in src/app/messages/data.ts, src/features/messages/*
The component set includes:
• chat list
• chat area
• message list
• header
• input
• video call component
This, combined with socket and encryption infrastructure elsewhere in the repo, indicates real-time messaging and call support as a distinct subsystem.
HR
HR has its own section shell and pages for:
• attendance
• salary
• staff
Associated modals suggest operational workflows for:
• adding staff
• leave requests
• role allowances
• package management
• doctor salary assignment
Accounts / Finance
src/app/accounts contains a broad finance module:
• audit trail
• bills
• expenses
• income
• insurance
• packages
• payouts
• pending
• reconciliation
• reports
• transactions
• vendors
• wallet
This looks like an accounting and settlement center for the clinic, with both operational and reporting views.
Registration and onboarding
The registration flow is split across multiple pages:
• src/app/register/page.tsx
• admin, licensing, location, terms
This is likely a guided onboarding/setup experience for clinic administrators. The presence of clinic_registration_schema.json suggests structured registration data or schema-driven validation in this area.
6) State management and data flow
The app uses Redux Toolkit-style feature slices:
• src/features/auth/authSlice.ts
• src/features/doctors/doctorSlice.ts
• src/features/messages/messageSlice.ts
• src/features/messages/messageTypes.ts
• src/features/notifications/notificationSlice.ts
• src/features/patients/patientSlice.ts
• src/features/patients/patientTypes.ts
The store is centralized in:
• src/store/index.ts
• src/store/rootReducer.ts
• src/store/provider.tsx
• src/store/storeRef.ts
This implies:
• a single global store for app-wide entities and session state
• feature-specific slices for domain data
• React hooks wrappers in src/hooks/useAppDispatch.ts and useAppSelector.ts
The likely data flow is:
1. a route page renders a domain component
2. that component reads state via typed selector hooks
3. user actions dispatch slice actions
4. slices update the store
5. UI re-renders from updated state
Because there are also local data.ts files under some routes, not all screens are necessarily backed by store data; some may be static or mock-driven while the architecture is being built out.
7) Real-time, calling, and security infrastructure
There is a dedicated real-time and communication layer:
• src/contexts/SocketContext.tsx
• src/services/socketService.ts
• src/components/providers/CallProvider.tsx
• src/components/providers/E2EEProvider.tsx
• src/hooks/useE2EE.ts
• src/utils/security.ts
This is important architecturally:
• Socket context and socket service indicate persistent real-time communication, probably for chat updates, presence, or notifications.
• CallProvider suggests audio/video call session management.
• E2EEProvider and security utilities indicate an encryption boundary around messaging/call data.
• The messaging UI (VideoCall, chat components) likely consumes these providers.
For an architecture diagram, this is a separate horizontal concern crossing the messages module and any call-related UI.
8) API and utility boundary
src/lib/api.ts is the clearest centralized API boundary. Even without seeing the implementation, it likely abstracts HTTP calls away from page and component code.
src/lib/utils.ts and src/utils/security.ts appear to hold shared helpers and security functions.
This suggests a boundary like:
• UI components and pages do not talk directly to external services
• they go through shared API/service modules and/or Redux thunks/slices
• domain-specific data transformations happen in feature or utility layers
9) Authentication and access control
The repo includes:
• login
• verify
• forgot/reset password
• onboarding
• registration
• src/components/auth/AuthGuard.tsx
• src/proxy.ts
This implies guarded routes and session-aware navigation. AuthGuard likely protects authenticated sections, while proxy.ts may enforce middleware-style routing or request interception at the app boundary.
10) Build, styling, and tooling
The project is a TypeScript Next.js app with:
• next.config.ts
• tailwind.config.ts
• postcss.config.mjs
• eslint.config.mjs
• tsconfig.json
Styling is almost certainly Tailwind-based, with custom UI primitives under src/components/ui.
The public directory serves static assets. The README confirms standard Next.js development and deployment on Vercel, so the runtime model is the usual Next.js client/server rendering with static assets and route-based code splitting.
11) How to think about the architecture diagram
A good diagram for this repository would show:
• A Next.js application shell at the top
• Route groups/modules beneath it:
- auth/onboarding
- registration
- dashboard/home
- patients
- doctors
- bookings
- messages
- HR
- accounts
- analytics
- settings
• A shared presentation layer:
- UI primitives
- molecules
- domain organisms
• A shared state/infrastructure layer:
- Redux store and feature slices
- API utilities
- socket/call/encryption providers
- auth guard/proxy
• Cross-cutting dependencies:
- messages and notifications depend on sockets
- messaging/call depends on encryption provider
- all major screens depend on shared layout/navigation and UI primitives
Overall, this is a modular clinic-management front end with strong domain separation, centralized client state, and real-time communication infrastructure layered on top of a Next.js App Router foundation.
Main entry points: index.ts Store · api.ts API client · layout.tsx Root layout · page.tsx Messages
Components 25
App shell
Root layouts and shared chrome that frame the clinic app.
- Root layout · Application-wide shell.
src/app/layout.tsx
Routes
User-facing app router modules and major workflows.
- Home · Landing dashboard/home page.
src/app/page.tsx - Onboarding · Authenticated onboarding flow.
src/app/(auth)/onboarding/page.tsx - Register · Clinic registration and setup entry point.
src/app/register/page.tsx - Patients · Patient list and entry point.
src/app/patients/page.tsx - Patient detail · Patient profile and record view.
src/app/patients/[id]/page.tsx - Doctors · Doctor directory and overview.
src/app/doctors/page.tsx - Doctor detail · Doctor profile, tabs, and schedule view.
src/app/doctors/[id]/page.tsx - Bookings · Booking list and management screen.
src/app/bookings/page.tsx - New booking · Multi-step booking creation flow.
src/app/bookings/new/page.tsx - Messages · Chat and calling workspace.
src/app/messages/page.tsx - HR staff · HR staff management view.
src/app/hr/staff/page.tsx - Accounts · Finance and reconciliation hub.
src/app/accounts/page.tsx - Settings · Application settings entry point.
src/app/settings/page.tsx
UI system
Reusable navigation and feature composition components.
- Sidebar · Primary dashboard navigation shell.
src/components/organisms/sidebar.tsx - Top nav · Top-level app header and controls.
src/components/organisms/top-nav.tsx - Booking wizard · Step-based booking creation UI.
src/components/organisms/bookings/booking-wizard.tsx - Chat area · Conversation panel for messages and calls.
src/components/organisms/messages/chat-area.tsx
State & infra
Global state, API, auth, and real-time/security services.
- Store · Central Redux store and provider entry.
src/store/index.ts - Message slice · Messaging state and actions.
src/features/messages/messageSlice.ts - API client · Shared HTTP/API abstraction.
src/lib/api.ts - Auth guard · Client-side route protection wrapper.
src/components/auth/AuthGuard.tsx - Socket context · Shared socket connection context.
src/contexts/SocketContext.tsx - Call provider · Call session and encryption provider layer.
src/components/providers/CallProvider.tsx - Security utils · Encryption and security utilities.
src/utils/security.ts
Connections 25
- Root layout → Sidebar: frames · Root shell composes persistent navigation.
- Root layout → Top nav: frames · Root shell includes top navigation.
- Root layout → Home: hosts · Main layout renders the dashboard route.
- Root layout → Auth guard: protects · Authenticated sections are wrapped by route protection.
- Home → API client: reads data · Dashboard screens use shared API access.
- Onboarding → API client: submits · Onboarding flow exchanges setup data through the API layer.
- Register → API client: submits · Registration screens rely on shared API calls.
- Patients → Store: reads state · Patient lists are driven from global feature state.
- Patient detail → Store: reads state · Patient detail views consume patient state.
- Doctors → Store: reads state · Doctor directory uses centralized state.
- Doctor detail → Store: reads state · Doctor profile tabs are backed by global state.
- Bookings → Store: reads state · Booking list binds to shared store data.
- New booking → Booking wizard: renders · New booking route is implemented with the wizard component.
- Booking wizard → API client: creates · Booking flow persists selections through the API layer.
- Messages → Chat area: renders · Messages page centers on the chat workspace.
- Messages → Message slice: uses · Messaging UI depends on feature state.
- Messages → Socket context: streams · Chat updates and presence rely on sockets.
- Chat area → Call provider: calls · Video or audio sessions are handled by the call layer.
- Call provider → Security utils: secures · Call and messaging traffic use security helpers.
- HR staff → API client: loads data · HR workflows use shared backend access.
- Accounts → API client: loads data · Finance screens depend on the API boundary.
- Settings → API client: loads data · Settings screens persist configuration via API calls.
- Store → Message slice: combines · Global store includes messaging feature state.
- Store → Socket context: integrates · Store-driven UI can react to socket events.
- Auth guard → Home: allows · Protected navigation continues into the main app.