inkithai/medimind

1. Purpose and entry points

MediMind is an anonymous medical-document intelligence workspace. It accepts PDFs/images, extracts structured clinical records, persists a patient snapshot, derives safety/lab insights, and supports cited retrieval Q&A.

Backend entry point: backend/api.py FastAPI app under /api/v1/. Frontend entry: frontend/src/main.tsx, routing/UI rooted in frontend/src/App.tsx.

2. Anonymous workspace and access boundary

A browser provisions an anonymous UUID/JWT session, stores credentials locally, and sends both bearer token and user ID on subsequent requests. The API validates identity and scopes every record, object path, and vector collection by user.

Core paths:

• backend/auth.py

• backend/api.py

• frontend/src/context/AuthContext.tsx

Public API surface is health/session creation; document, history, Q&A, conversation, and job endpoints are authenticated.

3. Upload and asynchronous processing orchestration

POST /documents accepts multipart files and either processes synchronously or creates an asynchronous parent job. Jobs expose independent per-file states plus batch finalization; a bounded shared worker pool controls provider load and handles partial failures without discarding successful files.

Core paths:

• backend/api.py

• backend/jobs.py

• frontend/src/pages/UploadPage.tsx

The frontend polls jobs and presents extraction progress separately from record finalization (timeline, safety, search indexing).

4. Extraction, validation, and clinical record assembly

The extraction pipeline reads PDF/image content and calls an OpenAI-compatible LLM provider for structured JSON. It supports Groq, Gemini, or generic providers, including multimodal vision models and fallback parsing/retry behavior. Extracted documents are filtered for medical relevance, merged with prior uploads, grouped into a timeline/snapshot, and checked for clinical conflicts.

Core paths:

• backend/medical_extractor.py

• backend/document_filter.py

• backend/docs/pipeline.md

Primary derived outputs are visits, medications, labs, allergies, safety cross-checks, and a structured patient timeline.

5. Persistence and file-storage split

Original files are uploaded to Cloudinary under a user-scoped mediscan/<user>/ path. Structured documents and patient snapshots are stored in Supabase Postgres. The schema enables RLS and is intended for service-role backend access; raw file bytes and LLM tokens are not stored in the database.

Core paths:

• backend/storage.py

• backend/db.py

• backend/supabase_schema.sql

Material external services: Cloudinary, Supabase, and the selected LLM provider. Runtime secrets and deployment configuration are defined through backend environment variables.

6. Analytics and retrieval boundary

Lab trends are deterministic Python computations over extracted lab values, dates, ranges, and crossings. Retrieval chunks structured timeline content, embeds it using OpenAI embeddings when available or local ONNX fallback, and indexes/searches through a pluggable vector-store layer.

Core paths:

• backend/lab_trends.py

• backend/retrieval.py

• backend/vector_store.py

Vector storage is either local Chroma (requires persistent volume) or Supabase chunks (brute-force cosine; deployment-friendly). Q&A self-heals by rebuilding a missing index from persisted documents.

7. Question answering, conversations, and workspace UI

Single-shot Q&A retrieves patient-scoped chunks and returns grounded answers, confidence, source citations, and professional-consultation guidance. In-memory conversations retain turns, rewrite follow-ups into standalone retrieval queries, and summarize old context; they are lost on process restart unless externally persisted.

Core paths:

• backend/conversation.py

• frontend/src/pages/QAPage.tsx

• frontend/src/pages/SessionPage.tsx

The React/Vite frontend renders the patient workspace: dashboard, document viewer, timeline, medicines, lab trends, safety, Q&A, and conversations. It communicates through the centralized client layer at frontend/src/api/client.ts.

8. Deployment runtime

Backend runs on Python 3.10+ with Uvicorn/FastAPI and is packaged for Railway via backend/Procfile and backend/Dockerfile. Frontend is React/TypeScript/Vite, with production hosting configuration in frontend/vercel.json. For Railway, Supabase vectors avoid a persistent disk; Chroma requires a mounted volume.

Core paths:

• backend/Procfile

• backend/Dockerfile

• frontend/vite.config.ts