Teaching Hospital Platform

A simulated hospital management system and medical-student clinical-education platform, sharing one backend, one database, and one role-based permission model, by Kudzaishe Majeza.

This is a portfolio/educational project. All data is fictional. It is not intended for real patient data, real diagnoses, or any real clinical use — see Section 10 of the architecture doc for more on that boundary.

Live demo: teaching-hospital-platform.vercel.app — sign in with the demo admin account below, or register as a patient.

Status: ✅ Phases 0–5 complete (0–4: core system; 5: visual identity). 🚧 Phase 6 (production-readiness hardening) under way: a separate dev/prod database and real file uploads are done; real email delivery, rate limiting, and a harder security pass are still pending.

Database

PostgreSQL via Neon. The runtime app connects through Neon's pooled endpoint using @prisma/adapter-pg; the Prisma CLI (migrations, seeding) uses the direct endpoint, configured in prisma.config.ts rather than schema.prisma (a Prisma 7 change).

What this is

Two connected halves:

1. Hospital management — patients, doctors, appointments, departments, clinical notes, diagnoses, prescriptions, test results.
2. Medical student education — placements, clinical shadowing (scoped, read-only access to specific appointments), learning activities, reflections, supervisor feedback, competency tracking, a logbook computed from real records.

The two connect through one relationship: a student can be assigned to shadow a specific doctor's appointment with explicitly scoped access — never unrestricted access to a patient's full record.

Full design rationale, the entity-relationship diagram, the permissions matrix, and the roadmap live in docs/architecture.md. Deliberate scope cuts (no self-service password reset, no rate limiting, etc.) are listed explicitly in that document's Known limitations section.

Tech stack

• Next.js 16 (App Router), TypeScript, Tailwind CSS
• PostgreSQL (Neon) + Prisma
• Auth.js (Credentials provider, JWT sessions with DB-checked revocation, bcrypt)
• shadcn/ui, Recharts
• Vitest + Playwright
• Deployed on Vercel

Running locally

npm install
cp .env.example .env.local   # then fill in your own Neon connection strings
npx prisma migrate dev       # applies the schema to your database
npx prisma db seed           # seeds roles, departments, competency catalog
npm run dev

Open http://localhost:3000.

Demo admin account (seeded, fictional — not a real credential, don't reuse this password anywhere real): [email protected] / DemoAdmin123!. Staff and student accounts are provisioned by an admin, not self-registered — sign in with this account and use /admin/staff or /admin/students to create them.

Testing

npm test

Unit tests (tests/unit/) cover the pure authorization logic in lib/permissions.ts. Integration tests (tests/integration/) run against the real development database — same connection as the app itself — and clean up after themselves. No mocking the database: these tests exist specifically to catch real authorization bugs ("can a patient deactivate another user?"), which a mocked Prisma client can't meaningfully verify.

npm run test:e2e

End-to-end tests (tests/e2e/, Playwright) drive a real, built app in a real browser through its critical journeys — login, a patient booking and a doctor completing an appointment with clinical records, a supervisor assigning shadowing through to a student's reflection and feedback, and admin account provisioning including a password reset. These exist for what the tests above structurally can't catch: a button whose onClick silently does nothing, a crash that only happens in a browser console. Runs against next build && next start, not next dev — real Neon network latency is generous-timeout territory here too, same reasoning as the integration tests.

Build log

• Phase 0, Stage 1 — Project setup, GitHub + Vercel pipeline
• Phase 0, Stage 2 — Database schema (Prisma + Neon)
• Phase 0, Stage 3 — Authentication
• Phase 0, Stage 4 — Core RBAC + audit logging
• Phase 1, Stage 1 — Dashboard shell + Department management
• Phase 1, Stage 2 — Staff management
• Phase 1, Stage 3 — Patient management
• Phase 1, Stage 4 — Appointments
• Phase 1, Stage 5 — Clinical records
• Phase 1, Stage 6 — Role dashboards
• Phase 2, Stage 1 — Student management
• Phase 2, Stage 2 — Clinical placements
• Phase 2, Stage 3 — Shadowing
• Phase 2, Stage 4 — Learning activities, reflections & feedback
• Phase 2, Stage 5 — Clinical logbook & competency tracking
• Phase 2, Stage 6 — Student dashboard
• Phase 3, Stage 1 — Notifications
• Phase 3, Stage 2 — Internal messaging
• Phase 3, Stage 3 — Search
• Phase 3, Stage 4 — Dashboard polish (Nurse dashboard)
• Phase 4, Stage 1 — Admin-assisted password reset
• Phase 4, Stage 2 — Security review & hardening
• Phase 4, Stage 3 — E2E tests (Playwright)
• Phase 4, Stage 4 — UI/UX polish

Phases 0–5 are complete: the original scope, plus a real visual identity and a round of production-readiness hardening. Phase 6 (the rest of that hardening) is under way. See docs/architecture.md for what each phase actually contains, including the two genuine bugs (dark mode never actually activating; a sequential-query latency bug on the activity detail page) found during Phase 5, and two infrastructure findings from Phase 6 Stage 2 (client-upload token generation needs a static Blob read-write token even though every other Blob operation accepts OIDC; the CSP's connect-src needed an explicit exception for the browser-to-Blob upload).