MedClaro is a full-stack personal health intelligence platform for organizing health profiles, medical documents, report analysis, prescription intelligence, timelines, family care, accessibility planning, future ecosystem modules, and release-readiness workflows.
The project is built as a Django REST Framework API with a Next.js App Router frontend. Current AI-powered features use deterministic mocked outputs so the product can be tested locally without live Gemini calls, while preserving separate Gemini configuration boundaries for production integration.
Phase 12 is complete. The repository includes:
- Django REST Framework backend under
backend. - Next.js frontend under
frontend. - Token-based authentication.
- Personal Health Profile APIs.
- Medical Vault document upload and soft-delete APIs.
- Mocked report analysis and biomarker storage.
- Health timeline, trend, and risk-awareness APIs.
- Mocked prescription and medication intelligence.
- Health Hub and contextual assistant planning.
- Daily health, symptom, journal, diet, and exercise planning.
- Family Care, Doctor Mode, and Emergency Mode planning.
- Accessibility, multilingual, voice, and senior mode planning.
- Future modules roadmap and ecosystem planning.
- Release readiness planning for tests, security, deployment, monitoring, backups, and disclaimers.
- Python
- Django
- Django REST Framework
- DRF token authentication
- PostgreSQL for local application data
- SQLite for test runs through
medclaro_api.test_settings
- Next.js 14 App Router
- React 18
- TypeScript
- Tailwind CSS
- Lucide React icons
- Planned model:
gemini-3.1-flash-lite - Separate Gemini environment variables per module:
- report analysis
- prescription intelligence
- health assistant
- trends
- diet/exercise
- translation
- doctor summary
- safety review
MedClaro/
|-- backend/
| |-- accounts/
| |-- accessibility/
| |-- ai_services/
| |-- audit/
| |-- daily_health/
| |-- documents/
| |-- family_care/
| |-- future_modules/
| |-- health_hub/
| |-- health_profiles/
| |-- health_trends/
| |-- medication_intelligence/
| |-- medclaro_api/
| |-- release_readiness/
| `-- report_analysis/
|-- docs/
| |-- Architecture.md
| |-- MasterPlan.md
| |-- Phase-01.md ... Phase-12.md
| |-- Progress.md
| `-- ReleaseReadiness.md
|-- frontend/
| |-- app/
| |-- lib/
| `-- package.json
|-- .env.example
`-- README.md
Install these before running the app:
- Python 3.10 or newer
- Node.js 18 or newer
- npm
- PostgreSQL
Create a local PostgreSQL database:
CREATE DATABASE medclaro;The default local credentials in .env.example use:
DATABASE_NAME=medclaro
DATABASE_USER=postgres
DATABASE_PASSWORD=shivamyadav
DATABASE_HOST=localhost
DATABASE_PORT=5432Update these values in .env if your PostgreSQL setup is different.
From the project root:
Copy-Item .env.example .envFor local development, keep:
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DJANGO_CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:3002,http://127.0.0.1:3002
DJANGO_CSRF_TRUSTED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:3002,http://127.0.0.1:3002
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000/api/v1Gemini API keys can stay empty for local testing because current AI behavior is deterministic and mocked.
Use two PowerShell windows: one for the backend and one for the frontend.
From the project root:
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver 127.0.0.1:8000Health check:
http://127.0.0.1:8000/api/v1/health/
Expected response:
{
"status": "ok",
"service": "medclaro-api",
"version": "v1"
}Open a second PowerShell window:
cd "D:\web devfiles\MedClaro\MedClaro\frontend"
npm install
npm.cmd run dev -- --hostname 127.0.0.1 --port 3000Open:
If port 3000 is busy:
npm.cmd run dev -- --hostname 127.0.0.1 --port 3002Then open:
Most app pages need a DRF token. Register a local user:
Invoke-RestMethod -Method Post `
-Uri "http://127.0.0.1:8000/api/v1/accounts/register/" `
-ContentType "application/json" `
-Body '{"username":"testuser","email":"test@example.com","password":"test-password-123"}'Copy the returned token and paste it into the token field on protected frontend pages.
If the user already exists, log in instead:
Invoke-RestMethod -Method Post `
-Uri "http://127.0.0.1:8000/api/v1/accounts/login/" `
-ContentType "application/json" `
-Body '{"username":"testuser","password":"test-password-123"}'/- main dashboard/profile- Personal Health Profile/documents- Medical Vault/reports- report analysis/trends- timeline and health trends/prescriptions- prescription intelligence/hub- Health Hub and assistant/daily- symptoms, journal, lifestyle planning/family- Family Care, Doctor Mode, Emergency Mode/accessibility- language, voice, senior mode/future- future modules and ecosystem roadmap/readiness- testing, security, deployment, monitoring, backup, and release readiness
Base URL:
http://127.0.0.1:8000/api/v1
Main API groups:
/accounts//profiles//documents//report-analyses//health-trends//prescriptions//health-hub//daily-health//family-care//accessibility//future-modules//release-readiness/
Backend tests use SQLite through medclaro_api.test_settings:
cd backend
.\.venv\Scripts\Activate.ps1
python manage.py test --settings=medclaro_api.test_settingsFrontend production build:
cd frontend
npm.cmd run buildBefore serving real users:
- Set
DJANGO_DEBUG=False. - Use a strong
DJANGO_SECRET_KEY. - Configure exact allowed hosts, CORS origins, and CSRF trusted origins.
- Enable HTTPS redirect, secure cookies, and HSTS after TLS is confirmed.
- Choose production object storage for uploaded medical documents.
- Choose monitoring and alerting providers.
- Configure PostgreSQL backups and run a restore drill.
- Review dependency audit findings.
- Review
docs/ReleaseReadiness.md.
MedClaro provides educational health organization and doctor-discussion support. It does not diagnose, prescribe, or replace qualified medical care. For severe symptoms, emergencies, or rapidly worsening conditions, contact local emergency services or a qualified clinician immediately.