Telemedicine Rural App

Production-style telemedicine platform built with Next.js, Express compatibility APIs, Prisma, Supabase Postgres/Auth/Realtime, Azure Blob Storage, and a React SPA.

This repository contains:

• Role-based telemedicine workflows for patients, doctors, help workers, and admins
• Real-time consultation support (video/audio/text signaling, chat, and shared call-end events)
• Prescription, pharmacy, lab, reminders, and document workflows
• Human-in-the-loop AI care-journey agents for no-show recovery and post-consultation follow-up
• Durable agent traces, approval gates, localized fallback, idempotent execution, and admin observability
• Azure-ready deployment flow and Capacitor mobile wrapper scaffolding

The AI agents are controlled care-coordination workflows, not autonomous doctors and not chatbots with unrestricted database/tool access.

They combine trusted clinical context, deterministic policy, AI-assisted wording, deterministic fallback, human approval, fixed server-side tools, durable execution, and audit/observability.

Why they exist:

• recover missed consultations without staff manually rebuilding the same workflow each time
• turn doctor-authored post-visit information into patient-friendly follow-up without changing medication instructions
• support multilingual patient communication
• remain useful when the AI provider is unavailable or returns invalid output
• ensure patient-facing actions remain approval-controlled, idempotent, and auditable

Detailed documentation:

• AI agents: purpose, architecture, workflows, safety, and testing
• Agent state machine and invariants
• Editable Draw.io workflow diagrams
• Rendered no-show recovery flow

The system is designed for mixed-connectivity and rural-first usage patterns:

• Patient booking and consultation lifecycle
• Doctor slot and analytics management
• Delegated care support through explicit consent
• Document and prescription handoff via secure access controls
• Operations visibility with impact and readiness metrics
• Human-reviewed AI care coordination for missed visits and post-visit follow-up

• Runtime: Next.js with Express compatibility APIs
• Database: Supabase Postgres via Prisma ORM
• Frontend: React + React Router inside a Next client boundary
• Realtime: Supabase Realtime for consultation signaling, chat, and agent operations updates
• Storage: Azure Blob Storage (with configurable local fallback)
• Auth: Supabase Auth cookies plus app-local role/profile rows
• AI: OpenRouter-backed structured planning with deterministic safe fallback
• Security: Helmet, rate limiting, role authorization
• Testing: Jest, Supertest, and Playwright E2E

.
|- app.js
|- apps/
|  |- backend/
|  |  |- controllers/
|  |  |- middleware/
|  |  |- models/
|  |  |- routes/
|  |  |- server/
|  |  |- services/
|  |- frontend/
|     |- src/
|- docs/
|  |- diagrams/
|  |  |- AI_AGENT_WORKFLOWS.drawio
|  |  |- ai-agent-architecture.svg
|  |  |- no-show-agent-flow.svg
|  |- AGENTIC_CARE_JOURNEY_AGENTS.md
|  |- AGENT_STATE_MACHINE.md
|- prisma/
|- scripts/
|- tests/
|- azure-deploy.md
|- design.md
|- docs/PRD.md
|- docs/production-readiness.md
|- docs/CAPACITOR.md

• Node.js 20+
• PostgreSQL 14+
• npm 10+
• Optional: Docker (for local postgres container)

run-app.bat

copy .env.example .env
docker compose up -d
npm install
npm run db:migrate
npm run db:seed
npm run dev

App URLs:

• API + SPA server: http://localhost:3000
• Frontend-only dev server (optional): http://localhost:5173 via npm run frontend:dev

Reference file: .env.example

• PORT
• NODE_ENV
• DATABASE_URL
• PRISMA_CONNECTION_LIMIT (recommended 1 on Vercel/serverless with Supabase Session Pooler)
• JWT_SECRET
• JWT_EXPIRES_IN

• APP_BASE_URL (comma-separated allowed web origins)
• ALLOW_NO_ORIGIN_SOCKET (default false)

• AZURE_STORAGE_CONNECTION_STRING
• AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY as an alternative to a full connection string
• AZURE_STORAGE_CONTAINER (default patient-documents)
• AZURE_STORAGE_PUBLIC_BASE_URL
• AZURE_UPLOADS_MODE (azure-only, local-only, etc.)

• OLLAMA_BASE_URL
• OLLAMA_MODEL (default llama3.1:8b)
• OLLAMA_TIMEOUT_MS (default 45000)
• OPENROUTER_API_KEY
• OPENROUTER_MODEL (default openai/gpt-oss-120b; legacy openai/gpt-oss-120b:free is normalized)
• OPENROUTER_TIMEOUT_MS (default 45000)
• AI_RATE_LIMIT_PER_MINUTE (default 40)

AI-provider success is not required for a safe workflow result. The agent layer validates model output and can use deterministic localized fallback when necessary.

• APPLICATIONINSIGHTS_CONNECTION_STRING (optional)
• SUPABASE_AUTH_CACHE_TTL_MS, APP_USER_CACHE_TTL_MS, DOCTOR_TRUST_CACHE_TTL_MS for short-lived performance caches
• ENABLE_REMINDER_CRON (true to auto-dispatch)
• REMINDER_CRON_INTERVAL_MS
• REMINDER_CRON_BATCH_LIMIT
• LOG_LEVEL

• ADMIN_INVITE_CODE (optional)

After npm run db:seed:

• Patient: patient.asha@example.com / Demo@12345
• Patient: patient.ravi@example.com / Demo@12345
• Doctor: doctor.asha@example.com / Demo@12345
• Doctor: doctor.ravi@example.com / Demo@12345
• Admin: admin.demo@example.com / Demo@12345
• Help worker: helper.meena@example.com / Demo@12345

Core startup path:

• app.js initializes env, telemetry, optional reminder cron, and server lifecycle
• apps/backend/server/create-app.js wires middleware, APIs, static assets, and SPA fallback
• apps/backend/server/create-server.js wraps the compatibility HTTP server for local/custom-server runs

Key middleware:

• Request context and request ID
• API mode adaptation for JSON clients
• Auth session attachment
• Role authorization
• Structured error handling

Agent orchestration is implemented as a separate bounded workflow layer. PostgreSQL is the source of truth; Realtime/polling only transport persisted workflow changes to the operations UI.

Both prefixes are active:

• /api/*
• /api/v1/*

Health and session:

• GET /health/live
• GET /health/ready
• GET /session

Domain route groups:

• /auth
• /users
• /doctors
• /patients
• /appointments
• /calls
• /prescriptions
• /documents
• /pharmacy
• /labs
• /reminders
• /support
• /ai
• /agents
• /admin/agents
• /innovations
• /medicines

OpenAPI baseline is maintained in docs/openapi.yaml.

Public routes:

• /
• /auth/login
• /auth/register
• /privacy-policy
• /terms-of-service
• /help-center

Authenticated routes:

• /dashboard
• /book
• /appointments
• /appointments/impact
• /appointments/:appointmentId
• /calls/:appointmentId
• /prescriptions/:appointmentId
• /doctors
• /doctors/:doctorId
• /doctors/me/slots (doctor)
• /doctors/me/analytics (doctor)
• /profile
• /users/me
• /patients/workspace (patient)
• /patients/me
• /medicines (patient)
• /pharmacy/orders
• /labs/tests
• /reminders
• /ai-copilot
• /admin/ai-agents (admin)
• /doctor/patient-access (doctor/admin)
• /innovations
• /support/consents (patient/help_worker)
• /pdf-preview

• Booking flow with doctor, slot, mode, and family context
• Appointment detail and lifecycle actions
• Presence and call readiness helpers
• No-show recovery ticket trigger

• Doctor prescription creation and update
• PDF generation and preview
• Handoff code support
• Patient medicine cabinet and medicine search

• Pharmacy order timeline and status updates
• Lab catalog, orders, status progression, and report attach
• PDF preview integration for reports and prescriptions

The repository contains two bounded AI-assisted agents:

• No-Show Recovery: doctor creates a recovery ticket; administrator starts planning; the system loads trusted context, validates policy/deduplication/language, calls AI or deterministic fallback, persists an immutable localized draft, stops for admin approval, then executes fixed safety-gated tools. The patient notification is created only after the final delivery gate.
• Post-Consultation Follow-Up: uses a doctor-authored prescription to create a patient-friendly summary, enforces medication fidelity, and proposes fixed summary/reminder actions.

Agent safety principles:

• AI drafts; backend policy decides what is allowed.
• AI cannot select arbitrary tools.
• Patient-facing side effects require human review/approval.
• Deterministic fallback keeps the workflow safe when AI is unavailable/invalid.
• Run/action/message idempotency protects against duplicate retries.
• Patient-visible no-show text must not expose internal URLs, route parameters, or UUIDs.
• Admin operations are driven by persisted database state/events.

See docs/AGENTIC_CARE_JOURNEY_AGENTS.md for the full design and docs/diagrams/AI_AGENT_WORKFLOWS.drawio for editable diagrams.

• Context endpoint and role-aware draft tools
• Draft note, reminder text, referral summary, async reply support
• Translation and helper guidance endpoints
• Review-required metadata policy for outputs

• Vitals and trends
• Care plans and check-ins
• Emergency escalation workflow
• External consult threads/messages
• Second-opinion request and audit trail
• Patient QR token sharing and doctor/admin access-by-token
• Consent and helper delegation controls

Primary models include:

• Identity and roles: User, PatientProfile, DoctorProfile
• Visits and consults: Slot, Appointment, CallSession, DoctorReview
• Clinical records: Document, Prescription, ConsultationVital, Referral
• Orders and tests: PharmacyOrder, LabTestCatalog, LabOrder, LabOrderItem
• Care coordination: ReminderJob, CareSupportLink, ConsentAudit, PatientAccessToken
• Agent workflow: AgentRun, AgentAction, AgentMessageDraft, AgentExecutionTrace, AgentExecutionEvent, AgentExecutionStep
• Extended innovation set: care plans, emergencies, external consult threads, voice notes, second opinions

Schema source of truth: prisma/schema.prisma

• Helmet CSP enabled
• Global rate limiting enabled
• Auth via secure cookie JWT/Supabase-backed session integration
• Role-gated endpoints and ACL checks
• Structured request IDs in response headers
• Readiness and liveness probes for orchestration
• Agent admin operations protected by administrator authorization
• Agent side effects use fixed tool allow-lists and idempotency
• Patient messages are delivery-gated and persisted before UI presentation
• Production schema verification guards critical agent workflow invariants

Run tests:

npm test

Current automated coverage includes:

• Session endpoint behavior
• Versioned API parity checks (/api vs /api/v1)
• Health endpoints
• SPA fallback rendering
• Unauthorized access baseline checks
• Agent planning and deterministic fallback
• Agent state/presentation rules
• Multilingual patient draft validation
• Patient notification behavior
• Execution-step sequence guards and workflow reliability

Extra QA reports and checklist outputs are available in qa-reports/.

• AI agents and workflow design: docs/AGENTIC_CARE_JOURNEY_AGENTS.md
• Agent state machine: docs/AGENT_STATE_MACHINE.md
• Editable Draw.io agent diagrams: docs/diagrams/AI_AGENT_WORKFLOWS.drawio
• API reference (route matrix): docs/API.md
• Azure deployment guide: azure-deploy.md
• Production readiness gates: docs/production-readiness.md
• Product requirements: docs/PRD.md
• UX and interaction design spec: design.md
• Capacitor wrapper workflow: docs/CAPACITOR.md

Capacitor configuration is included in capacitor.config.ts.

Use:

npm run mobile:sync
npm run mobile:add:android
npm run mobile:open:android

Current scope is wrapper readiness for the web app bundle (not native feature parity).

• Run npm run frontend:build
• Restart server with npm run dev

• Ensure PostgreSQL is reachable from DATABASE_URL
• Run npm run db:deploy (or npm run db:migrate locally)

• Run npm run prisma:generate

• Verify APP_BASE_URL is set to correct HTTPS origins
• Confirm NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are available to the browser
• Confirm Supabase Realtime is reachable from the deployed app

• If OpenRouter/Ollama is unavailable or model output fails validation, the bounded agent workflow can use deterministic fallback where supported
• Check persisted run/trace metadata for provider, model, fallback, and validation state
• A valid deterministic fallback is a safe degraded result, not automatically a failed workflow

• Inspect /admin/ai-agents
• Check canonical run/trace/action state rather than relying only on UI animation
• Use the admin integrity view/endpoint for state consistency checks
• Use safe retry only for eligible failures where idempotency guarantees no duplicate patient side effect