# ujjvxl/saathi architecture

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

- Interactive diagram: https://gitdiagram.com/ujjvxl/saathi
- Repository: https://github.com/ujjvxl/saathi

## Overview

Saathi is a shared elder-care application centered on a care circle. Members join and manage profiles, medication schedules, appointments and dose decisions; scheduled reminders escalate unconfirmed doses to responsible people and the wider circle, while activity and insights make care visible. The graph includes the documented voice-first elder mode and prescription scanning. Some subsystems are represented at their exact directory path because their source was not sampled; those links rely on README descriptions rather than inspected implementation.

Main entry points: [`src/lib/db.ts`](https://github.com/ujjvxl/saathi/blob/main/src/lib/db.ts) (Application database), [`src/lib/auth/dal.ts`](https://github.com/ujjvxl/saathi/blob/main/src/lib/auth/dal.ts) (Session and membership access), [`src/lib/reminders.ts`](https://github.com/ujjvxl/saathi/blob/main/src/lib/reminders.ts) (Reminder and escalation engine), [`src/app/(app)/p/[profileId]/page.tsx`](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/page.tsx) (Profile overview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and care circle"]
  node_auth["Sign in and join<br/>[page.tsx]"]
  node_access["Session and membership access<br/>[dal.ts]"]
  node_profiles["Care profiles and roles<br/>[profiles.ts]"]
  node_db[("Application database<br/>[db.ts]")]
end

subgraph group_care["Care operations"]
  node_dashboard["Care dashboard<br/>[page.tsx]"]
  node_profileview["Profile overview<br/>[page.tsx]"]
  node_medications["Medication schedules<br/>[page.tsx]"]
  node_doseactions["Dose decisions<br/>[doses.ts]"]
  node_appointments["Doctor appointments<br/>[page.tsx]"]
  node_circle["Circle and responsibilities<br/>[page.tsx]"]
  node_scan["Prescription scanning<br/>[route.ts]"]
  node_gemini["Gemini AI services<br/>[gemini.ts]"]
  node_schedule["Dose scheduling rules<br/>[schedule.ts]"]
end

subgraph group_followup["Reminders and accountability"]
  node_cron["Reminder scheduler<br/>[route.ts]"]
  node_reminders["Reminder and escalation engine<br/>[reminders.ts]"]
  node_alerts["Alert acknowledgement<br/>[page.tsx]"]
  node_timeline["Accountability timeline<br/>[page.tsx]"]
end

subgraph group_insights["Insights and elder access"]
  node_insightspage["Health insights<br/>[page.tsx]"]
  node_insightscore["Adherence calculations<br/>[insights-core.ts]"]
  node_weekly["Weekly summary email<br/>[weekly-summary.ts]"]
  node_elder["Voice-first elder mode<br/>[elder-mode.tsx]"]
end

node_members(("Elders and care circle"))
node_external["Email delivery"]

node_members -->|"sign in or join"| node_auth
node_auth -.->|"establishes session"| node_access
node_access -->|"checks membership"| node_db
node_dashboard -->|"loads member"| node_access
node_dashboard -.->|"loads care data"| node_db
node_profiles -.->|"manages profiles"| node_db
node_profileview -->|"requires membership"| node_access
node_profileview -.->|"loads profile data"| node_db
node_medications -.->|"manages schedules"| node_db
node_medications -.->|"requests scan"| node_scan
node_scan -->|"checks membership"| node_access
node_scan -->|"reads prescription"| node_gemini
node_gemini -->|"calls Gemini"| node_external
node_doseactions -.->|"records decisions"| node_db
node_profileview -->|"computes dose state"| node_schedule
node_appointments -.->|"manages visits"| node_db
node_circle -.->|"loads circle data"| node_db
node_cron -->|"runs reminders"| node_reminders
node_reminders -->|"reads and updates care data"| node_db
node_reminders -.->|"sends email"| node_external
node_members -->|"acknowledges follow-up"| node_alerts
node_alerts -.->|"records acknowledgement"| node_reminders
node_timeline -.->|"shows care activity"| node_db
node_insightspage -->|"summarizes dose history"| node_insightscore
node_insightspage -.->|"requests optional summary"| node_gemini
node_weekly -.->|"summarizes adherence"| node_insightscore
node_weekly -->|"sends weekly email"| node_external
node_elder -.->|"records confirmed doses"| node_doseactions
node_members -->|"uses elder mode"| node_elder

click node_auth "https://github.com/ujjvxl/saathi/blob/main/src/app/(auth)/login/page.tsx"
click node_access "https://github.com/ujjvxl/saathi/blob/main/src/lib/auth/dal.ts"
click node_profiles "https://github.com/ujjvxl/saathi/blob/main/src/app/actions/profiles.ts"
click node_db "https://github.com/ujjvxl/saathi/blob/main/src/lib/db.ts"
click node_dashboard "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/dashboard/page.tsx"
click node_profileview "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/page.tsx"
click node_medications "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/medications/page.tsx"
click node_doseactions "https://github.com/ujjvxl/saathi/blob/main/src/app/actions/doses.ts"
click node_appointments "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/appointments/page.tsx"
click node_circle "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/circle/page.tsx"
click node_scan "https://github.com/ujjvxl/saathi/blob/main/src/app/api/profiles/%5BprofileId%5D/scan/route.ts"
click node_gemini "https://github.com/ujjvxl/saathi/blob/main/src/lib/ai/gemini.ts"
click node_schedule "https://github.com/ujjvxl/saathi/blob/main/src/lib/schedule.ts"
click node_cron "https://github.com/ujjvxl/saathi/blob/main/src/app/api/cron/reminders/route.ts"
click node_reminders "https://github.com/ujjvxl/saathi/blob/main/src/lib/reminders.ts"
click node_alerts "https://github.com/ujjvxl/saathi/blob/main/src/app/alerts/ack/page.tsx"
click node_timeline "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/timeline/page.tsx"
click node_insightspage "https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/insights/page.tsx"
click node_insightscore "https://github.com/ujjvxl/saathi/blob/main/src/lib/insights-core.ts"
click node_weekly "https://github.com/ujjvxl/saathi/blob/main/src/lib/email/weekly-summary.ts"
click node_elder "https://github.com/ujjvxl/saathi/blob/main/src/components/elder/elder-mode.tsx"

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_auth,node_access,node_profiles,node_db toneBlue
class node_dashboard,node_profileview,node_medications,node_doseactions,node_appointments,node_circle,node_scan,node_gemini,node_schedule toneAmber
class node_cron,node_reminders,node_alerts,node_timeline toneMint
class node_insightspage,node_insightscore,node_weekly,node_elder toneRose
class node_members,node_external toneIndigo
```

## Components

### Identity and care circle

- [Sign in and join](https://github.com/ujjvxl/saathi/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Session and membership access](https://github.com/ujjvxl/saathi/blob/main/src/lib/auth/dal.ts): `src/lib/auth/dal.ts`
- [Care profiles and roles](https://github.com/ujjvxl/saathi/blob/main/src/app/actions/profiles.ts): `src/app/actions/profiles.ts`
- [Application database](https://github.com/ujjvxl/saathi/blob/main/src/lib/db.ts): `src/lib/db.ts`

### Care operations

- [Care dashboard](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/dashboard/page.tsx): `src/app/(app)/dashboard/page.tsx`
- [Profile overview](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/page.tsx): `src/app/(app)/p/[profileId]/page.tsx`
- [Medication schedules](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/medications/page.tsx): `src/app/(app)/p/[profileId]/medications/page.tsx`
- [Dose decisions](https://github.com/ujjvxl/saathi/blob/main/src/app/actions/doses.ts): `src/app/actions/doses.ts`
- [Doctor appointments](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/appointments/page.tsx): `src/app/(app)/p/[profileId]/appointments/page.tsx`
- [Circle and responsibilities](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/circle/page.tsx): `src/app/(app)/p/[profileId]/circle/page.tsx`
- [Prescription scanning](https://github.com/ujjvxl/saathi/blob/main/src/app/api/profiles/%5BprofileId%5D/scan/route.ts): `src/app/api/profiles/[profileId]/scan/route.ts`
- [Gemini AI services](https://github.com/ujjvxl/saathi/blob/main/src/lib/ai/gemini.ts): `src/lib/ai/gemini.ts`
- [Dose scheduling rules](https://github.com/ujjvxl/saathi/blob/main/src/lib/schedule.ts): `src/lib/schedule.ts`

### Reminders and accountability

- [Reminder scheduler](https://github.com/ujjvxl/saathi/blob/main/src/app/api/cron/reminders/route.ts): `src/app/api/cron/reminders/route.ts`
- [Reminder and escalation engine](https://github.com/ujjvxl/saathi/blob/main/src/lib/reminders.ts): `src/lib/reminders.ts`
- [Alert acknowledgement](https://github.com/ujjvxl/saathi/blob/main/src/app/alerts/ack/page.tsx): `src/app/alerts/ack/page.tsx`
- [Accountability timeline](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/timeline/page.tsx): `src/app/(app)/p/[profileId]/timeline/page.tsx`

### Insights and elder access

- [Health insights](https://github.com/ujjvxl/saathi/blob/main/src/app/(app)/p/%5BprofileId%5D/insights/page.tsx): `src/app/(app)/p/[profileId]/insights/page.tsx`
- [Adherence calculations](https://github.com/ujjvxl/saathi/blob/main/src/lib/insights-core.ts): `src/lib/insights-core.ts`
- [Weekly summary email](https://github.com/ujjvxl/saathi/blob/main/src/lib/email/weekly-summary.ts): `src/lib/email/weekly-summary.ts`
- [Voice-first elder mode](https://github.com/ujjvxl/saathi/blob/main/src/components/elder/elder-mode.tsx): `src/components/elder/elder-mode.tsx`

### Other components

- **Elders and care circle**
- **Email delivery**

## Connections

- Elders and care circle → Sign in and join: sign in or join
- Sign in and join → Session and membership access: establishes session
- Session and membership access → Application database: checks membership (evidence: `src/lib/auth/dal.ts`)
- Care dashboard → Session and membership access: loads member (evidence: `src/app/(app)/dashboard/page.tsx`)
- Care dashboard → Application database: loads care data
- Care profiles and roles → Application database: manages profiles
- Profile overview → Session and membership access: requires membership (evidence: `src/app/(app)/p/[profileId]/page.tsx`)
- Profile overview → Application database: loads profile data
- Medication schedules → Application database: manages schedules
- Medication schedules → Prescription scanning: requests scan
- Prescription scanning → Session and membership access: checks membership (evidence: `src/app/api/profiles/[profileId]/scan/route.ts`)
- Prescription scanning → Gemini AI services: reads prescription (evidence: `src/app/api/profiles/[profileId]/scan/route.ts`)
- Gemini AI services → Email delivery: calls Gemini (evidence: `src/lib/ai/gemini.ts`)
- Dose decisions → Application database: records decisions
- Profile overview → Dose scheduling rules: computes dose state (evidence: `src/app/(app)/p/[profileId]/page.tsx`)
- Doctor appointments → Application database: manages visits
- Circle and responsibilities → Application database: loads circle data
- Reminder scheduler → Reminder and escalation engine: runs reminders (evidence: `src/app/api/cron/reminders/route.ts`)
- Reminder and escalation engine → Application database: reads and updates care data (evidence: `src/lib/reminders.ts`)
- Reminder and escalation engine → Email delivery: sends email
- Elders and care circle → Alert acknowledgement: acknowledges follow-up
- Alert acknowledgement → Reminder and escalation engine: records acknowledgement
- Accountability timeline → Application database: shows care activity
- Health insights → Adherence calculations: summarizes dose history (evidence: `src/app/(app)/p/[profileId]/insights/page.tsx`)
- Health insights → Gemini AI services: requests optional summary (evidence: `src/app/(app)/p/[profileId]/insights/page.tsx`)
- Weekly summary email → Adherence calculations: summarizes adherence
- Weekly summary email → Email delivery: sends weekly email
- Voice-first elder mode → Dose decisions: records confirmed doses
- Elders and care circle → Voice-first elder mode: uses elder mode