# gurnooralagh/carecircle architecture

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

- Interactive diagram: https://gitdiagram.com/gurnooralagh/carecircle
- Repository: https://github.com/gurnooralagh/carecircle

## Overview

1. **Repository shape**
   - This is a two-tier product: a React/Vite frontend in `carecircle-frontend/` and a FastAPI backend in `New CareCircle project/`.
   - The frontend is the user-facing caregiver app; the backend owns authentication, document processing, medical analysis, and persistence through Supabase.

2. **Frontend boundary**
   - The React app is organized by route-level screens under `src/pages/` for auth, onboarding, dashboard, and upload/reconciliation flows.
   - Shared UI lives in `src/components/`, while application state is split across Zustand stores in `src/store/` for auth, patient context, uploads, and toasts.
   - `src/lib/api.ts` and `src/lib/supabase.ts` are the main integration points to the backend API and Supabase auth/session.

3. **User flow architecture**
   - The frontend is built around a linear onboarding flow: create account, collect patient details, upload documents, wait for processing, then show findings and an action plan.
   - After onboarding, the dashboard becomes the hub for medications, documents, and concern summaries.
   - Follow-up uploads feed a longitudinal comparison flow rather than a fresh one-time analysis.

4. **Backend API surface**
   - FastAPI route handlers are split by domain in `routers/`: `auth`, `onboarding`, `documents`, `dashboard`, and `longitudinal`.
   - This suggests a clean separation between user/session concerns, initial intake, document operations, dashboard reads, and post-onboarding change tracking.
   - `main.py` is the backend entry point, with configuration and logging centralized under `config/`.

5. **Core backend pipeline**
   - The main backend responsibility is a staged document-analysis pipeline implemented in `services/`.
   - `extraction_pipeline.py` orchestrates the processing flow; `ocr.py`, `pdf_extractor.py`, and `storage.py` handle document intake and file access.
   - The pipeline converts uploaded medical documents into structured data, then into concerns and action items.

6. **Document ingestion and extraction**
   - Uploaded files are first stored in Supabase Storage, then processed by two extraction paths: PDF text extraction and OCR for scanned/image-heavy documents.
   - The backend appears to merge extracted text, clean it, and then pass it to AI-backed extraction logic.
   - This makes file processing an async, multi-stage backend responsibility rather than a frontend task.

7. **AI and reasoning layer**
   - `services/llm.py` is the external model gateway, likely using OpenRouter to reach the LLMs mentioned in the README.
   - Structured extraction, summarization, and ranking are separated into specialized services such as `summary.py`, `action_summarizer.py`, `reasoning_engine.py`, and `orchestrator.py`.
   - This indicates the app does not rely on a single model call; it composes multiple AI passes for extraction, confidence handling, and user-facing language.

8. **Clinical logic subsystem**
   - Medical safety is handled in dedicated services: `drug_safety.py`, `flags.py`, `flag_generator.py`, `deduplicator.py`, and `resolver.py`.
   - These modules likely normalize medications, detect conflicts, and turn raw findings into higher-level “concerns.”
   - The architecture separates factual extraction from clinical interpretation, which is important for diagramming the trust boundaries.

9. **Longitudinal comparison subsystem**
   - Follow-up document uploads are handled by `longitudinal_pipeline.py`, `longitudinal_orchestration.py`, `longitudinal_comparison.py`, and `longitudinal_classification.py`.
   - This subsystem compares new documents against the existing patient record to detect added/removed medications, dose changes, escalated concerns, and resolved concerns.
   - It is distinct from the initial onboarding pipeline and is the main source of change tracking in the dashboard.

10. **Data and persistence**
   - Persistence is Supabase-backed PostgreSQL, with schema tracked in `db/schema.sql` and multiple migration files under `migrations/`.
   - `db/client.py` wraps database access, while `SUPABASE_SETUP.md` and `config/settings.py` indicate environment-driven connection setup.
   - Row Level Security is explicitly part of the system via `migrations/v3_8_rls.sql`, so authorization is enforced at the database layer as well as in the API.

11. **Domain models and contracts**
   - Request and response shapes are defined in `models/requests.py` and `models/responses.py`, which keeps API boundaries explicit.
   - This matters because the frontend and backend exchange structured medical entities, concern summaries, and processing states rather than ad hoc JSON.
   - The presence of these models suggests the backend is the source of truth for response formatting.

12. **Frontend data presentation**
   - The dashboard pages are organized by patient outcomes: findings, medications, documents, and profile.
   - Upload-specific screens under `pages/dashboard/upload/` and onboarding screens under `pages/onboarding/` map directly to backend processing stages.
   - Components such as `ConcernCard`, `MedicationCard`, `ProcessingScreen`, and `FileUploadZone` show that the UI is designed to surface processing status and medical interpretation, not just raw files.

13. **Operational/runtime concerns**
   - The stack is deployed as two separate runtimes: Vercel for the frontend and Railway for the backend, with `railway.toml` and `vercel.json` providing platform config.
   - The backend is Python 3.12 + Uvicorn/FastAPI; the frontend is React 19 + TypeScript + Vite.
   - This separation means API calls, auth sessions, file storage, and processing jobs cross infrastructure boundaries.

14. **Testing and validation**
   - The backend has a focused pytest suite covering auth, onboarding, OCR, PDF extraction, drug safety, longitudinal behavior, storage, summary generation, and extraction pipeline behavior.
   - That test layout mirrors the service decomposition, which is a good clue for architecture diagrams: each service area is independently testable and likely loosely coupled.

15. **Overall system diagram summary**
   - The core flow is: user uploads medical documents in the frontend → files are stored in Supabase → backend extracts text and runs AI/clinical analysis → database records and concern summaries are persisted → frontend reads the processed results for dashboard and longitudinal views.
   - The main architectural boundaries are frontend UI, backend API, document/AI pipeline, and Supabase persistence/auth/storage.

Main entry points: [`carecircle-frontend/src/lib/api.ts`](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/lib/api.ts) (API client), [`New CareCircle project/main.py`](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/main.py) (API entry), [`carecircle-frontend/src/App.tsx`](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/App.tsx) (App shell), [`New CareCircle project/services/extraction_pipeline.py`](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/services/extraction_pipeline.py) (Extraction pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["App shell<br/>react entry<br/>[App.tsx]"]
  node_fe_auth["Auth screens<br/>route pages<br/>[Login.tsx]"]
  node_fe_onboarding["Onboarding flow<br/>route pages"]
  node_fe_dashboard["Dashboard hub<br/>route pages"]
  node_fe_upload["Upload flow<br/>route pages<br/>[UploadTab.tsx]"]
  node_fe_components["UI kit<br/>components"]
  node_fe_state["Client state<br/>zustand stores<br/>[auth.ts]"]
  node_fe_api["API client<br/>http client<br/>[api.ts]"]
  node_fe_supabase["Supabase client<br/>auth client<br/>[supabase.ts]"]
end

subgraph group_backend["Backend"]
  node_be_main["API entry<br/>[main.py]"]
  node_be_auth["Auth API<br/>router<br/>[auth.py]"]
  node_be_onboarding["Onboarding API<br/>router<br/>[onboarding.py]"]
  node_be_docs["Documents API<br/>router<br/>[documents.py]"]
  node_be_dashboard["Dashboard API<br/>router<br/>[dashboard.py]"]
  node_be_longitudinal["Longitudinal API<br/>router<br/>[longitudinal.py]"]
  node_be_pipeline["Extraction pipeline<br/>service pipeline"]
  node_be_clinical["Clinical logic<br/>service cluster<br/>[drug_safety.py]"]
  node_be_ai["AI reasoning<br/>llm services<br/>[llm.py]"]
  node_be_long_pipeline["Longitudinal pipeline<br/>service pipeline"]
  node_be_models["API models<br/>schemas<br/>[requests.py]"]
  node_be_config["Config<br/>settings<br/>[settings.py]"]
end

subgraph group_data["Data"]
  node_be_db[("DB client<br/>supabase db<br/>[client.py]")]
  node_be_schema["Schema<br/>[schema.sql]"]
end

node_fe_app -->|"routes to"| node_fe_auth
node_fe_app -->|"routes to"| node_fe_onboarding
node_fe_app -->|"routes to"| node_fe_dashboard
node_fe_app -->|"routes to"| node_fe_upload
node_fe_auth -->|"auth via"| node_fe_supabase
node_fe_auth -->|"stores session"| node_fe_state
node_fe_onboarding -->|"uses UI"| node_fe_components
node_fe_dashboard -->|"uses UI"| node_fe_components
node_fe_upload -->|"uses UI"| node_fe_components
node_fe_state -->|"calls"| node_fe_api
node_fe_api -->|"sends contracts"| node_be_models
node_fe_api -->|"requests"| node_be_auth
node_fe_api -->|"requests"| node_be_onboarding
node_fe_api -->|"requests"| node_be_docs
node_fe_api -->|"requests"| node_be_dashboard
node_fe_api -->|"requests"| node_be_longitudinal
node_be_main -->|"loads"| node_be_config
node_be_main -->|"mounts"| node_be_auth
node_be_main -->|"mounts"| node_be_onboarding
node_be_main -->|"mounts"| node_be_docs
node_be_main -->|"mounts"| node_be_dashboard
node_be_main -->|"mounts"| node_be_longitudinal
node_be_docs -->|"runs"| node_be_pipeline
node_be_pipeline -->|"uses"| node_be_ai
node_be_pipeline -->|"produces"| node_be_clinical
node_be_pipeline -->|"persists"| node_be_db
node_be_longitudinal -->|"runs"| node_be_long_pipeline
node_be_long_pipeline -->|"compares"| node_be_clinical
node_be_ai -->|"reads/writes"| node_be_db
node_be_db -->|"implements"| node_be_schema
node_fe_supabase -->|"auth/session sync"| node_be_db

click node_fe_app "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/App.tsx"
click node_fe_auth "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/Login.tsx"
click node_fe_onboarding "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/onboarding/OnboardingLayout.tsx"
click node_fe_dashboard "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/dashboard/DashboardLayout.tsx"
click node_fe_upload "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/dashboard/upload/UploadTab.tsx"
click node_fe_components "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/components/ProcessingScreen.tsx"
click node_fe_state "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/store/auth.ts"
click node_fe_api "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/lib/api.ts"
click node_fe_supabase "https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/lib/supabase.ts"
click node_be_main "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/main.py"
click node_be_auth "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/routers/auth.py"
click node_be_onboarding "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/routers/onboarding.py"
click node_be_docs "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/routers/documents.py"
click node_be_dashboard "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/routers/dashboard.py"
click node_be_longitudinal "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/routers/longitudinal.py"
click node_be_pipeline "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/services/extraction_pipeline.py"
click node_be_clinical "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/services/drug_safety.py"
click node_be_ai "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/services/llm.py"
click node_be_long_pipeline "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/services/longitudinal_pipeline.py"
click node_be_models "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/models/requests.py"
click node_be_config "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/config/settings.py"
click node_be_db "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/db/client.py"
click node_be_schema "https://github.com/gurnooralagh/carecircle/blob/main/New CareCircle project/db/schema.sql"

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_fe_app,node_fe_auth,node_fe_onboarding,node_fe_dashboard,node_fe_upload,node_fe_components,node_fe_state,node_fe_api,node_fe_supabase toneBlue
class node_be_main,node_be_auth,node_be_onboarding,node_be_docs,node_be_dashboard,node_be_longitudinal,node_be_pipeline,node_be_clinical,node_be_ai,node_be_long_pipeline,node_be_models,node_be_config toneAmber
class node_be_db,node_be_schema toneMint
```

## Components

### Frontend

React/Vite caregiver app

- [App shell](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/App.tsx): react entry · Bootstraps the client app and top-level routing · `carecircle-frontend/src/App.tsx`
- [Auth screens](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/Login.tsx): route pages · Login, signup, password recovery, and email check flows · `carecircle-frontend/src/pages/Login.tsx`
- [Onboarding flow](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/onboarding/OnboardingLayout.tsx): route pages · Stepwise intake, upload, processing, and findings screens · `carecircle-frontend/src/pages/onboarding/OnboardingLayout.tsx`
- [Dashboard hub](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/dashboard/DashboardLayout.tsx): route pages · Main caregiver workspace for findings, medications, documents, and profile · `carecircle-frontend/src/pages/dashboard/DashboardLayout.tsx`
- [Upload flow](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/pages/dashboard/upload/UploadTab.tsx): route pages · Reconciliation and follow-up upload screens for longitudinal review · `carecircle-frontend/src/pages/dashboard/upload/UploadTab.tsx`
- [UI kit](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/components/ProcessingScreen.tsx): components · Shared cards, layouts, upload controls, and processing views · `carecircle-frontend/src/components/ProcessingScreen.tsx`
- [Client state](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/store/auth.ts): zustand stores · Auth, patient context, upload state, and toast state · `carecircle-frontend/src/store/auth.ts`
- [API client](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/lib/api.ts): http client · Frontend integration point for backend requests · `carecircle-frontend/src/lib/api.ts`
- [Supabase client](https://github.com/gurnooralagh/carecircle/blob/main/carecircle-frontend/src/lib/supabase.ts): auth client · Session and auth integration for the client app · `carecircle-frontend/src/lib/supabase.ts`

### Backend

FastAPI analysis and API service

- [API entry](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/main.py): fastapi entry · Backend startup and app assembly · `New CareCircle project/main.py`
- [Auth API](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/routers/auth.py): router · Session and user authentication endpoints · `New CareCircle project/routers/auth.py`
- [Onboarding API](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/routers/onboarding.py): router · Initial patient intake and onboarding submission endpoints · `New CareCircle project/routers/onboarding.py`
- [Documents API](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/routers/documents.py): router · Upload, ingestion, and document-processing endpoints · `New CareCircle project/routers/documents.py`
- [Dashboard API](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/routers/dashboard.py): router · Read endpoints for processed findings and caregiver views · `New CareCircle project/routers/dashboard.py`
- [Longitudinal API](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/routers/longitudinal.py): router · Follow-up comparison and change-tracking endpoints · `New CareCircle project/routers/longitudinal.py`
- [Extraction pipeline](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/services/extraction_pipeline.py): service pipeline · Orchestrates document intake, extraction, reasoning, and summary generation · `New CareCircle project/services/extraction_pipeline.py`
- [Clinical logic](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/services/drug_safety.py): service cluster · Drug safety, flags, deduplication, and resolution of concerns · `New CareCircle project/services/drug_safety.py`
- [AI reasoning](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/services/llm.py): llm services · Model gateway plus summarization, orchestration, and reasoning passes · `New CareCircle project/services/llm.py`
- [Longitudinal pipeline](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/services/longitudinal_pipeline.py): service pipeline · Classification and comparison for follow-up uploads against prior records · `New CareCircle project/services/longitudinal_pipeline.py`
- [API models](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/models/requests.py): schemas · Typed request and response contracts between client and backend · `New CareCircle project/models/requests.py`
- [Config](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/config/settings.py): settings · Environment, logging, and backend configuration · `New CareCircle project/config/settings.py`

### Data

Supabase-backed persistence and schema

- [DB client](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/db/client.py): supabase db · Database access wrapper for Supabase/Postgres · `New CareCircle project/db/client.py`
- [Schema](https://github.com/gurnooralagh/carecircle/blob/HEAD/New%20CareCircle%20project/db/schema.sql): sql schema · Primary database schema and migration track · `New CareCircle project/db/schema.sql`

## Connections

- App shell → Auth screens: routes to · Top-level routing exposes auth screens
- App shell → Onboarding flow: routes to · Guides new users through intake and uploads
- App shell → Dashboard hub: routes to · Main authenticated workspace
- App shell → Upload flow: routes to · Follow-up reconciliation and upload views
- Auth screens → Supabase client: auth via · Uses Supabase for session management
- Auth screens → Client state: stores session · Auth state is shared through client stores
- Onboarding flow → UI kit: uses UI · Shared upload and processing components
- Dashboard hub → UI kit: uses UI · Cards and dashboard presentation components
- Upload flow → UI kit: uses UI · Upload and reconciliation presentation components
- Client state → API client: calls · Client state drives API requests
- API client → API models: sends contracts · Frontend consumes typed request and response shapes
- API client → Auth API: requests · Authentication-related backend calls
- API client → Onboarding API: requests · Initial intake submission and patient setup
- API client → Documents API: requests · Document upload and processing operations
- API client → Dashboard API: requests · Fetches findings and dashboard data
- API client → Longitudinal API: requests · Follow-up comparison and change tracking
- API entry → Config: loads · App startup is driven by centralized configuration
- API entry → Auth API: mounts · Registers API routers
- API entry → Onboarding API: mounts · Registers API routers
- API entry → Documents API: mounts · Registers API routers
- API entry → Dashboard API: mounts · Registers API routers
- API entry → Longitudinal API: mounts · Registers API routers
- Documents API → Extraction pipeline: runs · Document endpoints trigger staged extraction
- Extraction pipeline → AI reasoning: uses · Extraction pipeline delegates to model-backed reasoning
- Extraction pipeline → Clinical logic: produces · Structured extraction is interpreted into concerns
- Extraction pipeline → DB client: persists · Stores processed results and document state
- Longitudinal API → Longitudinal pipeline: runs · Follow-up endpoints use longitudinal comparison pipeline
- Longitudinal pipeline → Clinical logic: compares · Reuses clinical interpretation for changes and resolutions
- AI reasoning → DB client: reads/writes · Model output is persisted with application data
- DB client → Schema: implements · Database access follows the tracked schema
- Supabase client → DB client: auth/session sync · Frontend auth sessions align with backend persistence
