MediKarya
AI-Powered Clinical Simulation Platform for Medical Students
Practice patient consultations, order diagnostics, and develop clinical reasoning — before your first real patient.
🌐 Live at medikarya.in
What is MediKarya?
MediKarya is a clinical education platform built for MBBS and medical students in India. It places students in the role of a doctor, facing a structured virtual patient case. Students conduct a simulated consultation via an AI-powered patient, order investigations from a real test library, submit a diagnosis and management plan, and receive detailed, scored feedback.
The platform is designed to reinforce structured clinical reasoning, patient safety awareness, and diagnostic discipline — with formative feedback that mimics the rigour of faculty assessment.
Key Features
- 🩺 AI Patient Chat — Powered by Google Gemini, patients respond in character from pre-scripted clinical facts, and in live cases their speech follows their condition
- 🚑 Live Simulations — A bedside encounter (monitor, clock, examination, timed investigations) for every case; authored live cases deteriorate in real time and respond to treatment
- 💳 Plans & Payments — Student (free) / Intern / Resident plans, monthly or yearly, as Razorpay subscriptions; plan limits enforced when a case starts
- 🧪 Investigation Ordering — A categorised test library (Lab, Imaging, Special) with pre-scripted results tied to each case
- 🧠 4-Layer Evaluation Engine — Hybrid algorithmic + LLM scoring across 5 clinical domains (100 marks total)
- 🚨 Red Flag Safety System — Two-system (rule + LLM) penalty detection for clinically critical missed questions
- 📊 Attempt History & Replay — Every completed case is saved; students can review full feedback from any past attempt
- 🏆 XP & Streaks — Gamified progress tracking stored per user
- 🔐 Role-based Access — Admin panel for faculty to view user progress and manage roles (via Clerk + Supabase)
- 📱 Mobile-first — Responsive layout with
100dvh simulation UI and safe-area padding
Tech Stack
| Layer | Technology |
|---|
| Framework | Next.js 15 (App Router) |
| Language | TypeScript |
| Styling | Tailwind CSS v4 + Radix UI primitives |
| Authentication | Clerk |
| Database | Supabase (PostgreSQL) |
| AI | Google Gemini (gemini-3.1-flash-lite for patient chat and quizzes, gemini-3.8-flash for classic-case evaluation) |
| Payments | Razorpay Subscriptions |
| Animations | Framer Motion + CSS |
| Smooth Scroll | Lenis |
| PWA | Serwist (@serwist/next) |
| Analytics | Vercel Speed Insights + Microsoft Clarity |
| Deployment | Self-hosted VPS / Vercel-compatible |
Project Structure
medikarya/
├── app/ # Next.js App Router pages & API routes
│ ├── page.tsx # Landing page (/)
│ ├── layout.tsx # Root layout (Clerk, fonts, analytics, JSON-LD)
│ ├── dashboard/ # Authenticated student area
│ │ └── cases/ # Case library + individual case pages
│ ├── admin/ # Admin panel (role-restricted)
│ ├── login/ & signup/ # Clerk authentication pages
│ ├── contact/ contribute/ # Marketing & community pages
│ ├── blog/ tutorials/ # Content pages
│ ├── early-contributors/ # Founding contributor recognition page
│ └── api/ # API routes
│ ├── cases/ # GET /api/cases, GET /api/cases/[id]
│ ├── chat/patient/ # POST patient chat + GET opening line
│ ├── tests/ # POST generate test result
│ ├── payments/ # Razorpay: create/verify/cancel subscription, webhook
│ ├── plan/ # GET the signed-in student's plan and today's usage
│ └── clerk-webhook/ # POST Clerk user creation webhook
│
├── components/ # Shared React components
│ ├── cases/ # Simulation UI (chat, test ordering, feedback)
│ └── ui/ # Radix UI-based design system components
│
├── engine/ # Evaluation & chat engine
│ ├── chatEngine.ts # Patient chat orchestrator
│ └── evaluation/
│ ├── EvaluationEngine.ts # 4-layer evaluation orchestrator
│ ├── DeterministicScorer.ts # Algorithmic test + history scoring
│ ├── IntentExtractor.ts # Clinical intent mapping & specificity
│ ├── ReasoningPromptBuilder.ts # LLM prompt construction
│ └── types.ts # Shared TypeScript interfaces
│
├── cases/
│ └── lib/red-flag-detector.ts # Tiered red flag penalty resolution
│
├── data/
│ └── cases/index.ts # All case data + CaseData type definition
│
├── app/actions/
│ └── evaluate.ts # Server action: run evaluation + persist to Supabase
│
├── hooks/ # Custom React hooks
├── lib/ # Utilities: Supabase client, simulation engine (lib/simulation),
│ # plan rules and access (lib/plans), payments (lib/payments)
├── types/ # Global TypeScript type definitions
└── public/ # Static assets
Getting Started
Prerequisites
1. Clone the repository
git clone https://github.com/your-org/medikarya.git
cd medikarya
2. Install dependencies
npm install
3. Configure environment variables
Create a .env.local file in the project root:
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Clerk (Authentication)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
CLERK_WEBHOOK_SECRET=whsec_...
# Clerk redirect paths
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/login
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/signup
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard
# Supabase (server-side only)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=...
# Google Gemini (patient chat, evaluation, quizzes)
GEMINI_API_KEY=AIza...
# Razorpay. Test and live mode are separate: keys, plans and webhooks all differ.
RAZORPAY_KEY_ID=rzp_test_...
RAZORPAY_KEY_SECRET=...
NEXT_PUBLIC_RAZORPAY_KEY_ID=rzp_test_...
RAZORPAY_WEBHOOK_SECRET=...
# One Razorpay plan per tier and billing period
RAZORPAY_PLAN_ID_INTERN=plan_...
RAZORPAY_PLAN_ID_RESIDENT=plan_...
RAZORPAY_PLAN_ID_INTERN_YEARLY=plan_...
RAZORPAY_PLAN_ID_RESIDENT_YEARLY=plan_...
4. Run the development server
npm run dev
Open http://localhost:3000.
Supabase Schema
The main tables (SQL for the newer ones is in scripts/, run in the Supabase SQL editor):
user_profiles
Stores user metadata synced from Clerk via webhook: user_id, email, name, role (student | admin), total_xp, current_streak, longest_streak, last_active_date.
case_attempts
Stores every completed evaluation: user_id, case_id, score, xp_earned, time_taken, feedback_json (full structured result), completed_at.
cases — the case library (case_json); a row wins over a bundled JSON file with the same id.
subscriptions — one row per Razorpay subscription (scripts/create_subscriptions_table.sql, scripts/add_subscription_cancel_at.sql).
case_starts — one row per student, case and day, which the plan limits count (scripts/create_case_starts_table.sql).
Adding a New Case
All cases live in data/cases/index.ts as a TypeScript array. To add a new case:
- Add a new entry to the
cases array conforming to the CaseData type
- Define the patient demographics, AI persona, pre-scripted test results, and
evaluation_config (required history, test classifications, accepted diagnoses, red flags)
- The case is automatically available in the case library — no route or component changes needed
For full field-by-field documentation, see CASE_SYSTEM_README.md.
Evaluation Engine
The scoring pipeline runs across 4 layers:
| Layer | Mechanism | Domains Scored |
|---|
| 1 — Intent Extraction | Rule-based NLP | Maps questions to clinical intents; scores specificity & redundancy |
| 2 — Deterministic Scoring | Algorithmic | Test ordering (0–20 pts) + 70% of History (0–17.5 pts) |
| 3 — LLM Scoring | Google Gemini | Clinical Reasoning (30), Diagnosis (15), Management (10), History Q (0–7.5) |
| 4 — Safety Penalties | Hybrid rule + LLM | Red flag missed penalty (−2 to −5 per flag) |
Total: 100 marks across Clinical Reasoning (30), History (25), Diagnosis (15), Testing (20), Management (10), minus safety penalties.
For the full technical and pedagogical reference, see EVALUATION_ENGINE.md.
Internal Documentation
| Document | Contents |
|---|
CASE_SYSTEM_README.md | Complete case flow, data architecture, API routes, components, and guide to adding new cases |
EVALUATION_ENGINE.md | Detailed scoring rubric, intent extraction, deterministic + LLM layers, red flag system, and design philosophy |
AI_INTEGRATION_GUIDE.md | Guide to the AI integrations and how to extend or replace the LLM layer |
Scripts
npm run dev # Start development server (Turbopack; restarts itself if it grows heavy, see scripts/dev.mjs)
npm run dev:webpack # Same, on webpack
npm run build # Production build
npm run start # Start production server
npm run lint # Run ESLint
License
This project is private and proprietary. All rights reserved by the MediKarya team.
MediKarya v2.0 — April 2026
Built for medical students in India. Made with ❤️ and clinical rigour.
