How oarisar/maya works
1. Repository shape
- This is a two-tier product: a React/TypeScript frontend in frontend/ and a FastAPI/Python backend in backend/.
- The application is a maternal-health assistant with a strong safety boundary: emergency detection happens before any retrieval or LLM generation.
2. Frontend as the user interaction layer
- The frontend is built with Vite, TanStack Router, Firebase Auth, and a component-heavy shadcn/ui setup.
- Major routes are login, dashboard, chat, docs, and emergency, which suggests the UI is organized around onboarding, ongoing care, document handling, and emergency escalation.
- src/lib/ contains client-side service wrappers for auth, chats, docs, theme, and Firebase, so the browser app is not just presentational; it also owns session state and persistence calls.
3. Frontend data and state boundaries
- src/contexts/lang-context.tsx and src/i18n/translations.ts indicate the app supports multilingual UI at the presentation layer.
- frontend/src/data/hospitals.json and the EmergencyMap component show that emergency guidance is partly backed by local structured data, not only backend AI.
- The UI also includes pregnancy-specific views such as PregnancyTracker, OnboardingFlow, and SettingsDialog, which implies a persistent health profile is central to the UX.
4. Backend as the orchestration layer
- The backend is organized into small responsibility-focused modules: main.py for API entrypoints, auth.py for identity/authorization, safety.py for emergency detection, rag.py for retrieval, llm.py for generation, and docs_store.py for document state/storage concerns.
- This backend is not a general app server; it is the decision engine that checks safety, fetches evidence, builds prompts, and streams answers.
5. Critical request flow
- The main conversational flow is: frontend sends a query → backend safety check runs → if safe, retrieval runs → prompt is assembled with patient context and evidence → Groq LLM streams the answer back.
- The README explicitly says the safety classifier runs before RAG and before the LLM, so the architecture has a hard safety gate at the top of the inference path.
- Responses are streamed, so the backend likely returns SSE/token deltas rather than waiting for a full completion.
6. Safety is a first-class subsystem
- backend/safety.py implements a deterministic-ish emergency classifier tuned for maternal red flags.
- If emergency patterns are detected, the system short-circuits normal generation and returns a structured emergency response.
- This is the most important architectural boundary in the repo: it prevents the generative model from being the first responder in a crisis.
7. Retrieval-Augmented Generation boundary
- backend/rag.py connects the assistant to a Pinecone vector index containing curated medical knowledge.
- The knowledge base is split into multiple namespaces for source separation, including WHO, ACOG, CDC, NHS, and related maternal-health references.
- Retrieved chunks carry metadata such as source title, URL, and section context so citations can be surfaced in the UI.
8. LLM and prompt assembly
- backend/llm.py is the generation layer, using Groq-hosted Llama 3.3 according to the README.
- Prompt construction is trimester-aware and includes chat history plus retrieved evidence; this makes the model context-rich but still constrained by retrieved sources.
- Citations are returned separately from the answer text, which is a useful architectural split for UI rendering and auditability.
9. Persistent health and chat data
- The app uses Firebase Authentication for Google sign-in and Firebase Realtime Database for user data persistence.
- The persisted data appears to include: pregnancy profile, medications, chat history, onboarding answers, reminders, and possibly document-derived health facts.
- frontend/src/lib/firebase.ts and the backend auth module indicate auth is a shared boundary: the frontend handles sign-in, while the backend likely verifies identity or permissions with service credentials.
10. Medical document upload and extraction path
- Upload handling is a distinct subsystem: lab reports and prescriptions are parsed from PDFs, then extracted values are folded into the user’s health profile and medication list.
- The backend uses pdfplumber for PDF extraction, and the README says lab extraction and report summarization run in parallel with asyncio.gather().
- This means uploads are not treated as just files; they are a data-ingestion path feeding the same longitudinal health model used by chat and tracking views.
11. Offline knowledge ingestion pipeline
- The notebooks/ folder contains scraping and chunking notebooks for web sources and embeddings, which signals that the knowledge base is built offline, not dynamically at request time.
- The vector content is prepared from authoritative sources, chunked by section, embedded with BAAI/bge-m3, and then upserted to Pinecone.
- This separation keeps runtime chat fast and stable while pushing heavy extraction/indexing work into preprocessing jobs.
12. Deployment and runtime footprint
- The backend is Dockerized via backend/Dockerfile, while the frontend has deployment config for Cloudflare Workers / Vercel-style hosting (wrangler.jsonc, vercel.json).
- That suggests a split deployment model: static/frontend delivery at the edge, plus an API backend hosted separately.
- The runtime dependencies are therefore externalized: Firebase for identity/data, Groq for inference, and Pinecone for retrieval.
13. What to emphasize in an architecture diagram
- Draw three major zones: client UI, Python API/orchestrator, and external services.
- Inside the backend, show the sequence: auth/safety → retrieval → prompt/LLM → streamed response.
- Show side flows from the frontend to Firebase for persistence, and from offline notebooks/backend utilities to Pinecone for knowledge ingestion.
- Make the safety gate visually dominant, since it is the defining architectural choice of the system.
Main entry points: src Frontend · main.py API Server · llm.py LLM Stream · chat.tsx Chat
Components 20
Client UI
React/TypeScript app for onboarding, chat, tracking, and emergency guidance.
- Frontend · Browser app with routed maternal-health workflows and local UI state.
frontend/src - Login · Authentication entry and onboarding to the app.
frontend/src/routes/login.tsx - Dashboard · Main health overview and pregnancy status surface.
frontend/src/routes/dashboard.tsx - Chat · Conversational assistant interface for maternal-health support.
frontend/src/routes/chat.tsx - Docs · Document upload and record review workspace.
frontend/src/routes/docs.tsx - Emergency · Emergency guidance and escalation screen.
frontend/src/routes/emergency.tsx - UI Kit · Reusable presentation components used across the app.
frontend/src/components/ui - Health Widgets · Pregnancy tracker, onboarding flow, settings, and emergency map.
frontend/src/components - Client Services · Browser wrappers for auth, chats, docs, theme, and Firebase.
frontend/src/lib - Language State · Multilingual UI context and translations.
frontend/src/contexts/lang-context.tsx
Python API
FastAPI backend that gates safety, retrieval, and generation.
- API Server · Backend entrypoint wiring auth, safety, RAG, and response streaming.
backend/main.py - Auth · Backend-side identity and authorization handling.
backend/auth.py - Safety Gate · Deterministic maternal-red-flag detection that short-circuits unsafe requests.
backend/safety.py - Retrieval · Fetches curated medical evidence from indexed namespaces.
backend/rag.py - LLM Stream · Builds prompt context and streams answer tokens.
backend/llm.py - Docs Store · Document-derived health facts and persistence helpers.
backend/docs_store.py
External Services
Hosted identity, persistence, vector search, and LLM services.
- Firebase · User identity and persistent app data storage.
- Pinecone · Curated maternal-health knowledge namespaces and metadata.
- Groq LLM · Hosted Llama 3.3 inference used for response generation.
Offline Ingestion
Preprocessing notebooks that build the knowledge base.
- Notebooks · Web scraping, chunking, and embedding preparation jobs.
notebooks
Connections 22
- Frontend → Login: route · Initial onboarding and sign-in entry.
- Frontend → Dashboard: route · Main health overview navigation.
- Frontend → Chat: route · Conversation workspace.
- Frontend → Docs: route · Document management workspace.
- Frontend → Emergency: route · Emergency guidance path.
- Frontend → UI Kit: renders · Shared UI primitives.
- Frontend → Health Widgets: renders · Pregnancy-specific experience surfaces.
- Frontend → Client Services: uses · Client-side auth, chat, docs, theme, and Firebase wrappers.
- Frontend → Language State: localizes · Language context and translation state.
- Client Services → Firebase: syncs · Authentication and persistent user data.
- Docs → Docs Store: updates · Document upload and extracted health facts.
- Chat → API Server: chat api · Sends user questions to the backend orchestrator.
- API Server → Auth: checks · Identity and permission boundary.
- API Server → Safety Gate: first · Emergency detection runs before retrieval and generation.
- Safety Gate → LLM Stream: short-circuit · Unsafe cases bypass normal generation and return emergency guidance.
- API Server → Retrieval: retrieves · Evidence lookup for safe requests.
- Retrieval → Pinecone: queries · Vector search over curated maternal-health sources.
- API Server → LLM Stream: generates · Prompt assembly and streamed response path.
- LLM Stream → Groq LLM: calls · Hosted Llama 3.3 inference.
- Docs Store → Firebase: persists · Longitudinal user records and extracted document state.
- Notebooks → Pinecone: builds · Offline scraping, chunking, embedding, and upsert pipeline.
- Frontend → Firebase: auth/data · Sign-in and user-state synchronization.