Telemedicine Rural App

Production-style telemedicine platform built with Express, Prisma, PostgreSQL, Socket.IO, 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 and chat)
• Prescription, pharmacy, lab, reminders, and document workflows
• AI-assisted draft tooling with review-required policy
• Azure-ready deployment flow and Capacitor mobile wrapper scaffolding

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

• Backend: Node.js, Express (CommonJS)
• Database: PostgreSQL via Prisma ORM
• Frontend: React + React Router + Vite
• Realtime: Socket.IO
• Storage: Azure Blob Storage (with configurable local fallback)
• Auth: Cookie-based JWT session
• Security: Helmet, rate limiting, role authorization
• Testing: Jest + Supertest

.
|- app.js
|- apps/
|  |- backend/
|  |  |- controllers/
|  |  |- middleware/
|  |  |- models/
|  |  |- routes/
|  |  |- server/
|  |  |- services/
|  |- frontend/
|     |- src/
|- docs/
|- 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
• HOST (use 0.0.0.0 to accept LAN/public traffic)
• NODE_ENV
• DATABASE_URL
• JWT_SECRET
• JWT_EXPIRES_IN

• APP_BASE_URL (comma-separated allowed web origins; wildcard patterns supported, e.g. https://*.example.com)
• ALLOW_NO_ORIGIN_SOCKET (default false)

• AZURE_STORAGE_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)
• AI_RATE_LIMIT_PER_MINUTE (default 40)

• APPLICATIONINSIGHTS_CONNECTION_STRING (optional)
• 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: patient1@example.com / Password123!
• Patient: patient2@example.com / Password123!
• Doctor: doctor1@example.com / Password123!
• Doctor: doctor2@example.com / Password123!
• Admin: admin@example.com / Password123!
• Help worker: helper1@example.com / Password123!

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 HTTP server + Socket.IO initialization

Key middleware:

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

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
• /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
• /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 follow-up action flow

• 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

• 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
• 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
• Role-gated endpoints and ACL checks
• Structured request IDs in response headers
• Readiness and liveness probes for orchestration

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

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

• API reference (route matrix): docs/API.md
• Azure deployment guide: azure-deploy.md
• AWS ECS deployment guide: docs/aws-ecs-deploy.md
• Phone access runbook: docs/phone-access-runbook.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 origins for the active domain(s)
• Use comma-separated origins or wildcard patterns (for example https://*.example.com) when needed
• Ensure WebSockets are enabled in host platform

• For Vite dev server, run npm run frontend:dev:lan (binds to 0.0.0.0)
• For backend-only serving on port 3000, ensure HOST=0.0.0.0
• Allow inbound firewall traffic on the exposed port
• If hosted behind HTTP only, set SKIP_HTTPS_REDIRECT=true until TLS is configured
• Run npm run check:access to detect common production-origin mistakes (for example localhost APP_BASE_URL)

• If OLLAMA_BASE_URL is unset/unreachable, AI endpoints use fallback-safe behavior
• Check API response metadata for fallback indicators