How sahoo-tech/health-connect works
1. Repository shape
- This is a two-part monorepo:
- health-connect: a Next.js frontend application.
- health-connect-api: a separate Express/TypeScript backend API.
- The split is a hard architectural boundary: the frontend renders UI and calls the API over HTTP/JSON; the backend owns booking logic and state.
2. Frontend subsystem (health-connect)
- Uses the Next.js App Router structure under src/app.
- Main user-facing surfaces are:
- public/marketing pages like home and about,
- authentication (/login),
- requester flows (/requester/...),
- admin flows (/admin/...).
- This suggests two distinct user roles: requester and admin.
3. Frontend page-level domains
- Requester area includes booking creation, booking detail, and requester dashboard.
- Admin area includes a dashboard and booking detail views.
- The routing structure implies role-based navigation and separate views over the same underlying booking data.
4. Frontend shared UI layer
- src/components contains reusable UI elements such as:
- Header, StatusBadge, Toast,
- SlotPicker for availability selection,
- visual/interaction helpers like AnimatedBackground, CursorEffect.
- These are presentation concerns only; they do not appear to own business state.
5. Frontend service/integration layer
- src/lib/api.ts is the client-side API adapter used to talk to the backend.
- src/lib/types.ts defines frontend-side data contracts.
- This isolates network calls and shared shapes from page components, which is important for diagramming the UI-to-API boundary.
6. Backend subsystem (health-connect-api)
- The API is organized as an Express app in TypeScript.
- src/index.ts is the main server entrypoint, with route modules under src/routes.
- api/index.ts and vercel.json indicate a deployment wrapper for serverless/hosted API entry, likely optimized for Vercel-style deployment.
7. Backend domain modules
- Route modules are split by responsibility:
- auth.ts for authentication/authorization,
- slots.ts for availability lookup,
- bookings.ts for booking creation and retrieval,
- admin.ts for administrative operations.
- This is the clearest place to draw backend subdomains: identity, availability, booking management, and admin control.
8. Backend state and persistence boundary
- src/store.ts indicates an in-memory store rather than a database-backed persistence layer.
- That means bookings/slots/state are maintained inside the API process, so the system is stateless at the HTTP contract level but not durable across process restarts.
- For an architecture diagram, this should be shown as “in-memory application state” rather than an external datastore.
9. Primary data flow
- A requester/admin page renders in the Next.js app.
- The page/component calls the backend through lib/api.ts.
- The backend routes request to the relevant domain module.
- Domain logic reads/writes the in-memory store and returns JSON.
- The frontend maps the response into UI state, e.g. slot lists, booking details, badges, and toasts.
10. Booking lifecycle
- The booking flow centers on availability discovery and reservation:
- fetch slots,
- select a slot,
- submit a booking,
- retrieve booking detail/status.
- Both requester and admin views likely read from the same booking model, but requester can initiate bookings while admin manages or reviews them.
11. Authentication/authorization boundary
- auth.ts suggests the backend controls login/session or token validation.
- The presence of separate admin routes implies role-based access control is enforced server-side, not just by hiding pages in the frontend.
- The login page in the frontend is therefore a gateway into role-specific sections.
12. Deployment/runtime implications
- Frontend: Next.js/React application, likely deployed as a web app with static and server-rendered routes.
- Backend: Express API with TypeScript, deployable independently from the frontend.
- The repo’s config files and deployment notes suggest the two services are intended to be deployed separately and integrated over a configured API base URL.
13. What is not present
- No database, message queue, search service, or external integration appears in the tree.
- No background worker or scheduled job subsystem is visible.
- So the architecture is intentionally simple: UI + HTTP API + in-memory store.
14. How to draw it
- Draw two top-level boxes: “Next.js Frontend” and “Express API.”
- Inside the frontend, separate public pages, requester pages, admin pages, and shared UI/lib.
- Inside the backend, separate route modules and a shared in-memory store.
- Show the frontend calling the backend via lib/api.ts, and the backend routes reading/writing store.ts.
Main entry points: api.ts API Client · index.ts Server Entry · bookings.ts Bookings Routes · admin.ts Admin Routes
Components 22
Next.js Frontend
React app with public, requester, and admin flows.
- Home · Public landing page.
health-connect/src/app/page.tsx - About · Public about page.
health-connect/src/app/about/page.tsx - Login · Authentication entry page.
health-connect/src/app/login/page.tsx - Requester Dash · Requester dashboard and booking overview.
health-connect/src/app/requester/dashboard/page.tsx - Book Slot · Requester booking creation flow.
health-connect/src/app/requester/book/page.tsx - Booking Detail · Requester booking detail view.
health-connect/src/app/requester/booking/[id]/page.tsx - Admin Dash · Admin dashboard and oversight view.
health-connect/src/app/admin/dashboard/page.tsx - Admin Detail · Admin booking detail view.
health-connect/src/app/admin/booking/[id]/page.tsx - Header · Shared top-level navigation.
health-connect/src/components/Header.tsx - Slot Picker · Availability selection control.
health-connect/src/components/SlotPicker.tsx - Status Badge · Booking/status display component.
health-connect/src/components/StatusBadge.tsx - Toast · Transient user feedback component.
health-connect/src/components/Toast.tsx - API Client · Frontend HTTP adapter for backend calls.
health-connect/src/lib/api.ts - Client Types · Frontend data contracts and shared shapes.
health-connect/src/lib/types.ts
Express API
TypeScript HTTP API with route modules and in-memory state.
- Server Entry · Express application bootstrap.
health-connect-api/src/index.ts - Auth Routes · Authentication and authorization endpoints.
health-connect-api/src/routes/auth.ts - Slots Routes · Availability lookup endpoints.
health-connect-api/src/routes/slots.ts - Bookings Routes · Booking creation and retrieval endpoints.
health-connect-api/src/routes/bookings.ts - Admin Routes · Administrative operations and oversight endpoints.
health-connect-api/src/routes/admin.ts - In-Memory Store · Application state for slots and bookings.
health-connect-api/src/store.ts - API Types · Backend domain types and response shapes.
health-connect-api/src/types.ts - API Wrapper · Serverless entry wrapper for hosted deployment.
health-connect-api/api/index.ts
Connections 32
- Home → Header: uses · Shared page chrome.
- About → Header: uses · Shared page chrome.
- Login → Header: uses · Shared page chrome.
- Requester Dash → API Client: calls · Loads requester data over HTTP.
- Book Slot → Slot Picker: uses · Selects available time slots.
- Book Slot → API Client: calls · Fetches slots and submits bookings.
- Booking Detail → Status Badge: uses · Shows booking state.
- Booking Detail → API Client: calls · Loads booking details.
- Admin Dash → API Client: calls · Fetches admin overview data.
- Admin Detail → Status Badge: uses · Shows booking state.
- Admin Detail → API Client: calls · Loads booking details.
- API Client → Client Types: uses · Shares client-side contracts.
- API Client → API Wrapper: http/json · Frontend talks to backend over HTTP.
- API Wrapper → Server Entry: loads · Hosted wrapper forwards to server entry.
- Server Entry → Auth Routes: mounts · Registers auth routes.
- Server Entry → Slots Routes: mounts · Registers slot routes.
- Server Entry → Bookings Routes: mounts · Registers booking routes.
- Server Entry → Admin Routes: mounts · Registers admin routes.
- Auth Routes → API Types: uses · Uses shared API types.
- Slots Routes → API Types: uses · Uses shared API types.
- Bookings Routes → API Types: uses · Uses shared API types.
- Admin Routes → API Types: uses · Uses shared API types.
- Auth Routes → In-Memory Store: reads/writes · Auth-related state access.
- Slots Routes → In-Memory Store: reads · Reads availability from memory.
- Bookings Routes → In-Memory Store: reads/writes · Creates and fetches bookings.
- Admin Routes → In-Memory Store: reads/writes · Admin state access.
- Login → Auth Routes: gateway · Login leads into server-side auth flow.
- Book Slot → Slots Routes: availability · Booking flow begins with slot lookup.
- Book Slot → Bookings Routes: reserve · Booking flow submits reservations.
- Booking Detail → Bookings Routes: detail · Requester booking detail comes from booking API.
- Admin Dash → Admin Routes: manage · Admin dashboard depends on admin endpoints.
- Admin Detail → Admin Routes: review · Admin detail view depends on admin endpoints.