# utkarsharma7/aha architecture

> Architecture diagram of the GitHub repository utkarsharma7/aha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utkarsharma7/aha
- Repository: https://github.com/utkarsharma7/aha

## Overview

#### Purpose and Runtime
This is a Next.js App Router healthcare application serving patient, clinician, practitioner, and administrator workflows. The root entry point is `src/app/page.js`; global application shell and styling begin at `src/app/layout.js` and `src/app/globals.css`. It runs as a Node.js/Next.js application with React client/server components and route handlers.

#### User-Facing Domains
Patient workflows cover health profiles, records, consultations, challenges, journeys, triage, emergency chat, and AI diagnosis. Key route families are `src/app/health-profile-2/page.jsx`, `src/app/records/page.js`, and `src/app/ai-diagnose-2/page.js`.

Plans are a major domain with separate care, diet, and exercise experiences: `src/app/plans/care/page.jsx`, `src/app/plans/diet/page.jsx`, and `src/app/plans/exercise/page.jsx`. Prescription and lab-report detail pages provide analysis, chat, correction, and plan-related views through `src/app/prescription/[id]/page.js` and `src/app/labreport/[id]/page.js`.

#### API Boundary and Backend Integration
The Next.js API layer is primarily a same-origin proxy boundary under `src/app/api/proxy`. It exposes domain-specific HTTP routes while isolating browser UI code from backend endpoint addressing and request mechanics; shared backend configuration is centered in `src/config/api.js` and client access is represented by `src/services/api.js`.

Proxy routes are organized by healthcare aggregate, including `src/app/api/proxy/patient/care_plan/overview/route.js`, `src/app/api/proxy/patient/diet/plan/propose/route.js`, and `src/app/api/proxy/modules/[moduleCode]/intake/route.js`. Dynamic route segments carry resource identity such as patient, plan, chat, report, phase, and invitation IDs.

#### Care-Plan and Coaching Lifecycle
Care planning is a staged workflow: retrieve an overview, capture/clarify/confirm goals, generate goal-track phases, review phases, and handle advancement decisions. The public UI and proxy implementation boundaries are `src/app/plans/care/page.jsx`, `src/lib/carePlanProxy.js`, and `src/app/api/proxy/patient/care_plan/phase/[phaseId]/advancement/suggest/route.js`.

Diet planning follows an analogous lifecycle: profile questionnaire → goal analysis/confirmation → proposal/plan confirmation → phase outline/generation → daily logging and coaching check-ins. Relevant paths are `src/app/plans/diet/components/GoalsManager.jsx`, `src/lib/dietProxy.js`, and `src/app/api/proxy/patient/diet/log/route.js`.

#### Conversations, Clinical Records, and Uploads
Chat is modeled as persistent sessions with start, turn, history/list, and specialized diagnosis, emergency, lab, prescription, triage, and care-episode variants. Core routes include `src/app/api/proxy/chat/start/route.js`, `src/app/api/proxy/diagnosisChat/turn/route.js`, and `src/app/api/proxy/patient/care-episode/[careEpisodeId]/chats/[chatSessionId]/turn/route.js`.

Clinical-document ingestion enters through lab-report and prescription uploads, then flows into report/prescription detail, analysis, correction, and care-episode planning. This boundary is represented by `src/app/api/proxy/upload/labreport/route.js`, `src/app/api/proxy/upload/prescription/route.js`, and `src/app/api/proxy/prescription/[id]/care-episode/plan/route.js`.

#### Roles, Access, and Operations
Authentication has dedicated API handlers, while role-specific UI shells guard patient and doctor views: `src/app/api/auth/authenticate/route.js`, `src/components/AuthGuard.jsx`, and `src/components/doctor/DoctorAuthGuard.jsx`. Doctor workflows are isolated under `src/app/doctor/layout.js`; invitations and patient selection support clinician-to-patient relationships.

Administrative observability is a separate surface for LLM calls, chat sessions, and turns, backed by an admin API proxy and service layer: `src/app/admin/observability/layout.jsx`, `src/app/api/admin/[...path]/route.js`, and `src/services/adminObservabilityApi.js`. Feature flags are centralized through `src/config/featureFlags.js` and `src/context/FeatureFlagContext.js`.

Main entry points: [`src/services/api.js`](https://github.com/utkarsharma7/aha/blob/newDesign/src/services/api.js) (Backend API client), [`src/app/layout.js`](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/layout.js) (App shell), [`src/app/api/proxy/chat/start/route.js`](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/chat/start/route.js) (Conversation proxy), [`src/app/prescription/[id]/page.js`](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/prescription/%5Bid%5D/page.js) (Clinical detail views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User applications"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.js]"]
  node_home["Home entry<br/>App Router page<br/>[page.js]"]
  node_patient_domains["Patient workflows<br/>route family<br/>[page.jsx]"]
  node_clinical_details["Clinical detail views<br/>route pages<br/>[page.js]"]
end

subgraph group_planning["Planning workflows"]
  node_care_ui["Care plans<br/>plan page<br/>[page.jsx]"]
  node_care_lifecycle["Care-plan lifecycle<br/>client proxy<br/>[carePlanProxy.js]"]
  node_diet_ui["Diet plans<br/>plan page<br/>[page.jsx]"]
  node_diet_goals["Diet goals<br/>client component<br/>[GoalsManager.jsx]"]
  node_diet_lifecycle["Diet lifecycle<br/>client proxy<br/>[dietProxy.js]"]
  node_exercise_ui["Exercise plans<br/>plan page<br/>[page.jsx]"]
end

subgraph group_api["Next.js API boundary"]
  node_api_client["Backend API client<br/>[api.js]"]
  node_api_config["Backend configuration<br/>[api.js]"]
  node_care_proxy["Care-plan proxy<br/>route handler<br/>[route.js]"]
  node_diet_proxy["Diet proxy<br/>route handler<br/>[route.js]"]
  node_chat_proxy["Conversation proxy<br/>route handlers<br/>[route.js]"]
  node_document_ingestion["Document ingestion<br/>route handlers<br/>[route.js]"]
  node_backend[("Healthcare backend<br/>external backend")]
end

subgraph group_platform["Access and operations"]
  node_access["Authentication and guards<br/>access control<br/>[route.js]"]
  node_doctor_app["Doctor workspace<br/>role shell<br/>[layout.js]"]
  node_admin_observability["Admin observability<br/>admin surface<br/>[layout.jsx]"]
  node_admin_api["Admin proxy<br/>route handler<br/>[route.js]"]
  node_feature_flags["Feature flags<br/>feature control"]
end

node_app_shell -->|"hosts"| node_home
node_app_shell -->|"hosts"| node_patient_domains
node_app_shell -->|"hosts"| node_care_ui
node_app_shell -->|"applies access"| node_access
node_patient_domains -->|"conversations"| node_chat_proxy
node_clinical_details -->|"uploads"| node_document_ingestion
node_clinical_details -->|"clinical chat"| node_chat_proxy
node_care_ui -->|"coordinates"| node_care_lifecycle
node_care_lifecycle -->|"same-origin calls"| node_care_proxy
node_diet_ui -->|"captures goals"| node_diet_goals
node_diet_goals -->|"drives"| node_diet_lifecycle
node_diet_lifecycle -->|"same-origin calls"| node_diet_proxy
node_care_proxy -->|"forwards via"| node_api_client
node_diet_proxy -->|"forwards via"| node_api_client
node_chat_proxy -->|"forwards via"| node_api_client
node_document_ingestion -->|"forwards via"| node_api_client
node_api_client -.->|"uses"| node_api_config
node_api_client -->|"backend requests"| node_backend
node_doctor_app -->|"guarded by"| node_access
node_admin_observability -->|"queries"| node_admin_api
node_admin_api -->|"observability requests"| node_backend
node_app_shell -.->|"consumes"| node_feature_flags

click node_app_shell "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/layout.js"
click node_home "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/page.js"
click node_patient_domains "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/health-profile-2/page.jsx"
click node_clinical_details "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/prescription/%5Bid%5D/page.js"
click node_care_ui "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/care/page.jsx"
click node_care_lifecycle "https://github.com/utkarsharma7/aha/blob/newDesign/src/lib/carePlanProxy.js"
click node_diet_ui "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/diet/page.jsx"
click node_diet_goals "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/diet/components/GoalsManager.jsx"
click node_diet_lifecycle "https://github.com/utkarsharma7/aha/blob/newDesign/src/lib/dietProxy.js"
click node_exercise_ui "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/exercise/page.jsx"
click node_api_client "https://github.com/utkarsharma7/aha/blob/newDesign/src/services/api.js"
click node_api_config "https://github.com/utkarsharma7/aha/blob/newDesign/src/config/api.js"
click node_care_proxy "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/patient/care_plan/overview/route.js"
click node_diet_proxy "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/patient/diet/log/route.js"
click node_chat_proxy "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/chat/start/route.js"
click node_document_ingestion "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/upload/labreport/route.js"
click node_access "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/auth/authenticate/route.js"
click node_doctor_app "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/doctor/layout.js"
click node_admin_observability "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/admin/observability/layout.jsx"
click node_admin_api "https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/admin/%5B...path%5D/route.js"
click node_feature_flags "https://github.com/utkarsharma7/aha/blob/newDesign/src/context/FeatureFlagContext.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_home,node_patient_domains,node_clinical_details toneBlue
class node_care_ui,node_care_lifecycle,node_diet_ui,node_diet_goals,node_diet_lifecycle,node_exercise_ui toneAmber
class node_api_client,node_api_config,node_care_proxy,node_diet_proxy,node_chat_proxy,node_document_ingestion,node_backend toneMint
class node_access,node_doctor_app,node_admin_observability,node_admin_api,node_feature_flags toneRose
```

## Components

### User applications

- [App shell](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/layout.js): Next.js layout · Provides the global application shell and styling. · `src/app/layout.js`
- [Home entry](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/page.js): App Router page · `src/app/page.js`
- [Patient workflows](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/health-profile-2/page.jsx): route family · Health profiles, records, consultations, triage, emergency chat, and AI diagnosis. · `src/app/health-profile-2/page.jsx`
- [Clinical detail views](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/prescription/%5Bid%5D/page.js): route pages · Prescription and lab-report analysis, correction, chat, and planning views. · `src/app/prescription/[id]/page.js`

### Planning workflows

- [Care plans](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/care/page.jsx): plan page · `src/app/plans/care/page.jsx`
- [Care-plan lifecycle](https://github.com/utkarsharma7/aha/blob/newDesign/src/lib/carePlanProxy.js): client proxy · Coordinates overview, goals, phases, review, and advancement. · `src/lib/carePlanProxy.js`
- [Diet plans](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/diet/page.jsx): plan page · `src/app/plans/diet/page.jsx`
- [Diet goals](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/diet/components/GoalsManager.jsx): client component · Captures and confirms diet goals. · `src/app/plans/diet/components/GoalsManager.jsx`
- [Diet lifecycle](https://github.com/utkarsharma7/aha/blob/newDesign/src/lib/dietProxy.js): client proxy · Handles proposals, phases, logs, and coaching check-ins. · `src/lib/dietProxy.js`
- [Exercise plans](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/plans/exercise/page.jsx): plan page · `src/app/plans/exercise/page.jsx`

### Next.js API boundary

- [Backend API client](https://github.com/utkarsharma7/aha/blob/newDesign/src/services/api.js): service · Shared client access to backend services. · `src/services/api.js`
- [Backend configuration](https://github.com/utkarsharma7/aha/blob/newDesign/src/config/api.js): configuration · Central backend endpoint configuration. · `src/config/api.js`
- [Care-plan proxy](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/patient/care_plan/overview/route.js): route handler · Same-origin care-plan overview and lifecycle boundary. · `src/app/api/proxy/patient/care_plan/overview/route.js`
- [Diet proxy](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/patient/diet/log/route.js): route handler · Same-origin diet proposal, phases, and logging boundary. · `src/app/api/proxy/patient/diet/log/route.js`
- [Conversation proxy](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/chat/start/route.js): route handlers · Persistent chat sessions, turns, and specialized clinical conversations. · `src/app/api/proxy/chat/start/route.js`
- [Document ingestion](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/proxy/upload/labreport/route.js): route handlers · Accepts lab-report and prescription uploads. · `src/app/api/proxy/upload/labreport/route.js`
- **Healthcare backend**: external backend · Domain APIs for clinical data, plans, chats, and processing.

### Access and operations

- [Authentication and guards](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/auth/authenticate/route.js): access control · Authentication handlers and patient/doctor UI guards. · `src/app/api/auth/authenticate/route.js`
- [Doctor workspace](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/doctor/layout.js): role shell · Clinician workflows, invitations, and patient selection. · `src/app/doctor/layout.js`
- [Admin observability](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/admin/observability/layout.jsx): admin surface · Observes LLM calls, chat sessions, and turns. · `src/app/admin/observability/layout.jsx`
- [Admin proxy](https://github.com/utkarsharma7/aha/blob/newDesign/src/app/api/admin/%5B...path%5D/route.js): route handler · `src/app/api/admin/[...path]/route.js`
- [Feature flags](https://github.com/utkarsharma7/aha/blob/newDesign/src/context/FeatureFlagContext.js): feature control · Centralized feature-flag context. · `src/context/FeatureFlagContext.js`

## Connections

- App shell → Home entry: hosts
- App shell → Patient workflows: hosts
- App shell → Care plans: hosts
- App shell → Authentication and guards: applies access
- Patient workflows → Conversation proxy: conversations
- Clinical detail views → Document ingestion: uploads
- Clinical detail views → Conversation proxy: clinical chat
- Care plans → Care-plan lifecycle: coordinates
- Care-plan lifecycle → Care-plan proxy: same-origin calls
- Diet plans → Diet goals: captures goals
- Diet goals → Diet lifecycle: drives
- Diet lifecycle → Diet proxy: same-origin calls
- Care-plan proxy → Backend API client: forwards via
- Diet proxy → Backend API client: forwards via
- Conversation proxy → Backend API client: forwards via
- Document ingestion → Backend API client: forwards via
- Backend API client → Backend configuration: uses
- Backend API client → Healthcare backend: backend requests
- Doctor workspace → Authentication and guards: guarded by
- Admin observability → Admin proxy: queries
- Admin proxy → Healthcare backend: observability requests
- App shell → Feature flags: consumes