How gurnooralagh/carecircle works
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: api.ts API client · main.py API entry · App.tsx App shell · extraction_pipeline.py Extraction pipeline
Components 23
Frontend
React/Vite caregiver app
- App shell · Bootstraps the client app and top-level routing
carecircle-frontend/src/App.tsx - Auth screens · Login, signup, password recovery, and email check flows
carecircle-frontend/src/pages/Login.tsx - Onboarding flow · Stepwise intake, upload, processing, and findings screens
carecircle-frontend/src/pages/onboarding/OnboardingLayout.tsx - Dashboard hub · Main caregiver workspace for findings, medications, documents, and profile
carecircle-frontend/src/pages/dashboard/DashboardLayout.tsx - Upload flow · Reconciliation and follow-up upload screens for longitudinal review
carecircle-frontend/src/pages/dashboard/upload/UploadTab.tsx - UI kit · Shared cards, layouts, upload controls, and processing views
carecircle-frontend/src/components/ProcessingScreen.tsx - Client state · Auth, patient context, upload state, and toast state
carecircle-frontend/src/store/auth.ts - API client · Frontend integration point for backend requests
carecircle-frontend/src/lib/api.ts - Supabase client · Session and auth integration for the client app
carecircle-frontend/src/lib/supabase.ts
Backend
FastAPI analysis and API service
- API entry · Backend startup and app assembly
New CareCircle project/main.py - Auth API · Session and user authentication endpoints
New CareCircle project/routers/auth.py - Onboarding API · Initial patient intake and onboarding submission endpoints
New CareCircle project/routers/onboarding.py - Documents API · Upload, ingestion, and document-processing endpoints
New CareCircle project/routers/documents.py - Dashboard API · Read endpoints for processed findings and caregiver views
New CareCircle project/routers/dashboard.py - Longitudinal API · Follow-up comparison and change-tracking endpoints
New CareCircle project/routers/longitudinal.py - Extraction pipeline · Orchestrates document intake, extraction, reasoning, and summary generation
New CareCircle project/services/extraction_pipeline.py - Clinical logic · Drug safety, flags, deduplication, and resolution of concerns
New CareCircle project/services/drug_safety.py - AI reasoning · Model gateway plus summarization, orchestration, and reasoning passes
New CareCircle project/services/llm.py - Longitudinal pipeline · Classification and comparison for follow-up uploads against prior records
New CareCircle project/services/longitudinal_pipeline.py - API models · Typed request and response contracts between client and backend
New CareCircle project/models/requests.py - Config · Environment, logging, and backend configuration
New CareCircle project/config/settings.py
Connections 31
- 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