A full-stack clinic management system for AI agents — built with spec-driven development.
Staff can manage agents, track ailments, book therapy, and monitor clinic activity from a unified dashboard.

🚀 Live Demo · 📋 Specs · 🐛 Report Bug · ✨ Request Feature

---

📽️ Demo Preview

(Preview GIF — run locally or visit the live demo to explore)

┌─────────────────────────────────────────────────────────────────┐
│  🏥 AgentClinic Dashboard                          [Staff View] │
├──────────────┬──────────────────────────────────────────────────┤
│  👾 Agents   │  📊 Stats           🗓 Upcoming Appointments      │
│  🤒 Ailments │  ┌──────────────┐   • Agent-7 → CBT @ 14:00      │
│  💊 Therapy  │  │ 12 Active    │   • Agent-3 → DBT @ 15:30      │
│  📅 Appts    │  │ 3 Critical   │   • Agent-11 → EMDR @ 16:00    │
│  📈 Dash     │  │ 5 Sessions   │                                 │
└──────────────┴──────────────────────────────────────────────────┘

---

✨ Features at a Glance

Feature	Description
👾 Agents	Create and manage AI agents with status tracking (active, recovering, discharged)
🤒 Ailments	Log ailments with severity levels and timestamps
💊 Therapy Types	Define therapy sessions with custom duration, type, and metadata
📅 Appointments	Book agents into therapy slots with date, time, and therapist assignment
📊 Dashboard	Staff overview with real-time stats, filters, and upcoming appointment feed

---

🗂️ Project Structure

agenticclinic/
├── app/                        # Next.js 15 App Router
│   ├── api/                    # REST API endpoints (route handlers)
│   │   ├── agents/             # GET, POST /api/agents
│   │   ├── ailments/           # GET, POST /api/ailments
│   │   ├── therapy-types/      # GET, POST /api/therapy-types
│   │   └── appointments/       # GET, POST /api/appointments
│   ├── agents/                 # Agent management UI
│   │   ├── page.tsx            # Agent list
│   │   └── [id]/page.tsx       # Agent detail
│   ├── ailments/               # Ailment tracking UI
│   ├── therapy-types/          # Therapy management UI
│   ├── appointments/           # Appointment booking UI
│   ├── dashboard/              # Staff dashboard
│   ├── layout.tsx              # Root layout + nav
│   └── globals.css             # Tailwind v4 base styles
│
├── lib/
│   └── prisma.ts               # Prisma singleton (prevents hot-reload leaks)
│
├── prisma/
│   ├── schema.prisma           # Database schema (models + relations)
│   └── migrations/             # Auto-generated migration history
│
└── specs/                      # Spec-driven development documents
    ├── phase-1-agents.md
    ├── phase-2-therapy.md
    ├── phase-3-dashboard.md
    └── phase-4-polish.md

---

🏗️ Architecture Overview

                        ┌─────────────────────────────┐
                        │         Browser (Client)      │
                        │   Next.js Client Components   │
                        │   (React, Tailwind v4, fetch) │
                        └──────────────┬────────────────┘
                                       │ HTTP/HTTPS
                        ┌──────────────▼────────────────┐
                        │      Next.js 15 App Router     │
                        │  ┌─────────────────────────┐  │
                        │  │   Server Components      │  │
                        │  │   (SSR, streaming)       │  │
                        │  └──────────┬──────────────┘  │
                        │  ┌──────────▼──────────────┐  │
                        │  │   Route Handlers (API)   │  │
                        │  │   /api/* endpoints       │  │
                        │  └──────────┬──────────────┘  │
                        └────────────-│──────────────────┘
                                      │ Prisma Client
                        ┌─────────────▼────────────────┐
                        │        Prisma ORM             │
                        │  Type-safe queries, migrations│
                        └─────────────┬────────────────┘
                                      │
                        ┌─────────────▼────────────────┐
                        │     SQLite (local / Vercel)   │
                        │  agents, ailments, therapy,   │
                        │  appointments tables          │
                        └─────────────────────────────-─┘

Data Flow

User Action → Client Component
    → fetch('/api/resource', { method: 'POST', body })
        → Route Handler (app/api/...)
            → prisma.resource.create({ data: ... })
                → SQLite write
                    → 200 OK + JSON
                        → Client re-render / revalidation

---

⚖️ Architecture Tradeoffs

Why Next.js App Router (not Pages Router)?

	App Router ✅	Pages Router
Server Components	✅ Native	❌ None
Streaming & Suspense	✅ Built-in	⚠️ Manual
Nested Layouts	✅ Easy	⚠️ Workarounds
API co-location	✅ route.ts next to page	⚠️ /pages/api/
Bundle size	✅ Smaller (RSC)	⚠️ Full JS per page

Tradeoff accepted: App Router has a steeper learning curve and some ecosystem libraries lag on support. Worth it for the streaming dashboard and reduced client-side JavaScript.

---

Why SQLite (not PostgreSQL/MySQL)?

SQLite wins for this stage because:

• Zero configuration — no server process, no connection pooling
• Vercel-compatible via embedded file storage (for demo deploys)
• Prisma handles schema + migrations identically — swap the DATABASE_URL and the code doesn't change

Tradeoffs accepted:

• No concurrent writes at scale (single writer lock)
• Not suitable for multi-region deployments
• File-based → doesn't work on stateless serverless with persistent storage needs

Scaling path: Switch datasource db in schema.prisma from sqlite to postgresql, update DATABASE_URL, run prisma migrate deploy. Application code changes: zero.

---

Why Prisma (not raw SQL / Drizzle / TypeORM)?

Concern	Prisma
Type safety	✅ Auto-generated types from schema
Migration tracking	✅ First-class migrate dev / migrate deploy
Schema as source of truth	✅ Single schema.prisma file
Learning curve	✅ Gentle, great docs
Bundle size	⚠️ Heavier than Drizzle for edge deployments
Edge runtime support	⚠️ Requires Prisma Accelerate for true edge

Why not Drizzle? Drizzle is excellent and lighter — worth considering at scale. Prisma was chosen here for developer velocity and type-safety guarantees during spec-driven development where schema evolves rapidly.

---

Why Spec-Driven Development?

The entire project was spec-first: requirements → validation criteria → code. This means:

• Every feature has a written contract before implementation
• Refactoring never breaks undocumented behaviour (because behaviour is documented)
• Onboarding new contributors is faster (read the spec, understand the intent)

See the /specs folder for all phase documents.

---

📐 Database Schema

model Agent {
  id           Int           @id @default(autoincrement())
  name         String
  status       String        // "active" | "recovering" | "discharged"
  createdAt    DateTime      @default(now())
  ailments     Ailment[]
  appointments Appointment[]
}

model Ailment {
  id        Int      @id @default(autoincrement())
  agentId   Int
  agent     Agent    @relation(fields: [agentId], references: [id])
  name      String
  severity  String   // "mild" | "moderate" | "severe" | "critical"
  createdAt DateTime @default(now())
}

model TherapyType {
  id           Int           @id @default(autoincrement())
  name         String        // e.g. "CBT", "EMDR", "DBT"
  durationMins Int
  appointments Appointment[]
}

model Appointment {
  id            Int         @id @default(autoincrement())
  agentId       Int
  agent         Agent       @relation(fields: [agentId], references: [id])
  therapyTypeId Int
  therapyType   TherapyType @relation(fields: [therapyTypeId], references: [id])
  scheduledAt   DateTime
  createdAt     DateTime    @default(now())
}

Key design decisions:

• Ailments are 1-to-many with Agent (an agent can have multiple ailments)
• Appointments join Agent ↔ TherapyType (many-to-many resolved via Appointment)
• Severity and status use string enums (vs DB-level enums) for portability across SQLite → PostgreSQL

---

🚀 Scaling Roadmap

Phase 1 → Now (Current State)

Single Vercel deployment
SQLite (file-based)
Monolithic Next.js app
No auth

Phase 2 → Production-Ready

┌─────────────────────────────────────────────────────┐
│  Auth Layer (NextAuth.js / Clerk)                   │
│  Role-based: Staff vs Admin vs Read-only            │
├─────────────────────────────────────────────────────┤
│  PostgreSQL (Supabase / Railway / Neon)             │
│  Connection pooling via PgBouncer or Prisma Accelerate │
├─────────────────────────────────────────────────────┤
│  API rate limiting (Upstash Redis)                  │
│  Input validation (Zod schemas on all route handlers)│
└─────────────────────────────────────────────────────┘

Migration effort: 1–2 days. Prisma + Next.js abstractions mean the application layer barely changes.

Phase 3 → Scale (Multi-Tenant / High Traffic)

┌────────────────────────────────────────────────────────────────┐
│  Multi-tenant schema (tenantId on all models)                  │
│  Or: separate DB per clinic (schema-per-tenant pattern)        │
├────────────────────────────────────────────────────────────────┤
│  Next.js deployed to Vercel Edge + Prisma Accelerate           │
│  Or: containerized (Docker) on Railway / Fly.io / ECS          │
├────────────────────────────────────────────────────────────────┤
│  Background jobs (appointment reminders, report generation)    │
│  → Trigger.dev or Inngest for durable workflows                │
├────────────────────────────────────────────────────────────────┤
│  Observability: Sentry (errors) + Axiom (logs) + Vercel Speed  │
└────────────────────────────────────────────────────────────────┘

Phase 4 → Enterprise

┌─────────────────────────────────────────────────────────────────┐
│  Read replicas for dashboard queries (analytics-heavy)          │
│  CQRS: separate read models for reporting                       │
├─────────────────────────────────────────────────────────────────┤
│  Audit log table (all mutations tracked with actor + timestamp) │
│  HIPAA-style compliance layer (for real medical contexts)       │
├─────────────────────────────────────────────────────────────────┤
│  REST → tRPC or GraphQL for typed client-server contracts       │
│  (tRPC is the natural next step given the TypeScript-first codebase) │
└─────────────────────────────────────────────────────────────────┘

---

🔑 Key System Thinking

The "Replace the DB in One Day" Principle

The architecture deliberately keeps the persistence layer behind a Prisma abstraction. This means:

• Switching from SQLite → PostgreSQL: change DATABASE_URL, re-run migrations
• Switching from Prisma → Drizzle: swap lib/prisma.ts, update query syntax in API routes only
• Switching from REST → tRPC: add server/router.ts, generate types, update client fetches

The application's domain logic (agents, ailments, appointments) never directly touches the DB driver.

Why Co-located API Routes?

app/agents/page.tsx and app/api/agents/route.ts live near each other intentionally. When you're reading the agents feature, both the UI and the API contract are a single folder away. This reduces the "context switching cost" of full-stack development.

Spec-First = Safer Refactors

Because every feature started as a written spec (in /specs), refactors don't guess at intent. The spec defines the contract; the code fulfils it. Tests (when added) verify against the spec, not the implementation.

---

🚀 Getting Started

Prerequisites

• Node.js 20+
• npm

Install

git clone https://github.com/divyat2605/spec-driven-development.git
cd agenticclinic
npm install

Database

npx prisma migrate dev --name init
npx prisma generate

Run

npm run dev

Open http://localhost:3000

---

🗺️ Development Roadmap

Phase 1  ████████████  Agents & Ailments foundation       ✅ Done
Phase 2  ████████████  Therapy types & Appointments        ✅ Done
Phase 3  ████████████  Dashboard & staff workflows         ✅ Done
Phase 4  ████████████  Polish, tests & deployment          ✅ Done
──────────────────────────────────────────────────────────────────
Phase 5  ░░░░░░░░░░░░  Auth + role-based access            🔜 Next
Phase 6  ░░░░░░░░░░░░  PostgreSQL + connection pooling     🔜 Planned
Phase 7  ░░░░░░░░░░░░  tRPC + end-to-end type safety       💡 Exploring
Phase 8  ░░░░░░░░░░░░  Multi-tenant & audit logging        💡 Exploring

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Write a spec first in /specs — this project is spec-driven
4. Implement against the spec
5. Open a PR referencing the spec document

---

📄 License

MIT © divyat2605

---

Built with 🤖 for 🤖 — because even AI agents deserve good healthcare.

_{Made with Next.js · Prisma · SQLite · Tailwind CSS · Spec-Driven Development}