elevenlabs-webhook-nodejs 1.0.0

package/docs/API_ENDPOINTS.md

@@ -0,0 +1,344 @@
+# API Endpoints Reference
+
+> 174 REST endpoints across 25 controllers
+> Base URL: `/api` (frontend proxy) or direct `:3005`
+
+---
+
+## Auth (`/auth`) — 10 endpoints
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| POST | `/auth/login` | — | Login with email + password |
+| POST | `/auth/register` | — | Register new tenant with owner account |
+| POST | `/auth/refresh` | — | Refresh access token |
+| POST | `/auth/logout` | JWT | Logout and invalidate session |
+| POST | `/auth/change-password` | JWT | Change password (requires current) |
+| POST | `/auth/forgot-password` | — | Request password reset link |
+| POST | `/auth/reset-password` | — | Reset password with token |
+| GET | `/auth/me` | JWT | Get current user info + permissions |
+| GET | `/auth/me/schedule` | JWT | Get own doctor working hours |
+| PUT | `/auth/me/schedule` | JWT | Update own doctor working hours |
+
+---
+
+## Patients (`/patients`) — 28 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/patients` | `patients:read` | List patients (paginated, search, clinic filter) |
+| GET | `/patients/search` | `patients:read` | Quick search autocomplete |
+| POST | `/patients` | `patients:create` | Create patient |
+| GET | `/patients/:id` | `patients:read` | Get patient detail |
+| PUT | `/patients/:id` | `patients:update` | Update patient |
+| DELETE | `/patients/:id` | `patients:delete` | Soft-delete patient |
+| GET | `/patients/:id/medical-history` | `patients:read` | Get medical history (decrypted) |
+| PUT | `/patients/:id/medical-history` | `patients:update` | Update medical history |
+| GET | `/patients/:id/notes` | `patients:read` | List notes |
+| POST | `/patients/:id/notes` | `patients:update` | Create note |
+| PUT | `/patients/:id/notes/:noteId` | `patients:update` | Update note |
+| DELETE | `/patients/:id/notes/:noteId` | `patients:update` | Delete note |
+| GET | `/patients/:id/documents` | `patients:read` | List documents |
+| POST | `/patients/:id/documents` | `patients:update` | Upload document (base64) |
+| GET | `/patients/:id/documents/:docId` | `patients:read` | Get document with signed URL |
+| GET | `/patients/:id/documents/:docId/file` | `patients:read` | Stream file (proxy, supports `?token=`) |
+| DELETE | `/patients/:id/documents/:docId` | `patients:update` | Delete document |
+| GET | `/patients/:id/photo-sets` | `patients:read` | List photo sets |
+| POST | `/patients/:id/photo-sets` | `patients:update` | Create photo set |
+| GET | `/patients/:id/photo-sets/:setId` | `patients:read` | Get photo set with signed URLs |
+| PUT | `/patients/:id/photo-sets/:setId` | `patients:update` | Update photo set metadata |
+| DELETE | `/patients/:id/photo-sets/:setId` | `patients:update` | Delete photo set + all photos |
+| POST | `/patients/:id/photo-sets/:setId/photos` | `patients:update` | Upload photo (base64, generates thumbnail) |
+| DELETE | `/patients/:id/photo-sets/:setId/photos/:photoId` | `patients:update` | Delete single photo |
+| GET | `/patients/:id/examinations` | `patients:read` | List examinations |
+| POST | `/patients/:id/examinations` | `patients:update` | Create examination (appointment optional) |
+| GET | `/patients/:id/examinations/:examId` | `patients:read` | Get examination (decrypted) |
+| PUT | `/patients/:id/examinations/:examId` | `patients:update` | Update examination |
+
+---
+
+## Appointments (`/appointments`) — 10 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/appointments` | `appointments:read` | List (paginated, status/doctor/date filters) |
+| GET | `/appointments/stats` | `appointments:read` | Stats (today, upcoming, by status/source) |
+| GET | `/appointments/availability` | `appointments:read` | Check available slots (`?clinicId&date&doctorId`) |
+| GET | `/appointments/patient/:patientId` | `appointments:read` | Patient's appointments |
+| GET | `/appointments/doctor/:doctorId` | `appointments:read` | Doctor's schedule |
+| POST | `/appointments` | `appointments:manage` | Create appointment |
+| GET | `/appointments/:id` | `appointments:read` | Get detail |
+| PUT | `/appointments/:id` | `appointments:manage` | Update (reschedule, change doctor) |
+| PUT | `/appointments/:id/status` | `appointments:manage` | Update status (confirm/start/complete/cancel/no-show) |
+| DELETE | `/appointments/:id` | `appointments:manage` | Cancel appointment |
+
+---
+
+## Treatments (`/treatments`) — 6 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/treatments` | `treatments:read` | List (optional `?clinicId`) |
+| GET | `/treatments/categories` | `treatments:read` | Distinct categories |
+| POST | `/treatments` | `treatments:manage` | Create treatment |
+| GET | `/treatments/:id` | `treatments:read` | Get single |
+| PUT | `/treatments/:id` | `treatments:manage` | Update |
+| DELETE | `/treatments/:id` | `treatments:manage` | Soft-delete |
+
+## Treatment Plans (`/treatment-plans`) — 8 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/treatment-plans/patient/:patientId` | `patients:read` | List plans for patient |
+| POST | `/treatment-plans/patient/:patientId` | `treatment_plans:manage` | Create plan |
+| GET | `/treatment-plans/:id` | `patients:read` | Get plan with items |
+| PUT | `/treatment-plans/:id` | `treatment_plans:manage` | Update plan |
+| DELETE | `/treatment-plans/:id` | `treatment_plans:manage` | Delete (no completed items) |
+| POST | `/treatment-plans/:id/items` | `treatment_plans:manage` | Add item |
+| PUT | `/treatment-plans/:id/items/:itemId` | `treatment_plans:manage` | Update item status |
+| DELETE | `/treatment-plans/:id/items/:itemId` | `treatment_plans:manage` | Remove item (not completed) |
+
+---
+
+## Users (`/users`) — 10 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/users` | `users:read` | List users for tenant |
+| GET | `/users/doctors` | `users:read` | List doctors with profiles |
+| GET | `/users/:id` | `users:read` | Get user |
+| POST | `/users/invite` | `users:invite` | Invite new user |
+| PUT | `/users/:id` | `users:update` | Update user (name, role, permissions) |
+| PUT | `/users/:id/clinics` | `users:update` | Update clinic assignments |
+| DELETE | `/users/:id` | `users:delete` | Deactivate user |
+| GET | `/users/:id/doctor-profile` | `users:read` | Get doctor profile |
+| PUT | `/users/:id/doctor-profile` | `users:update` | Upsert doctor profile |
+| GET | `/users/:id/doctor-profile/availability` | `users:read` | Doctor availability for date |
+
+---
+
+## Clinics (`/clinics`) — 10 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/clinics` | `clinics:read` | List clinics (scoped by user access) |
+| GET | `/clinics/:id` | `clinics:read` | Get clinic + calendar + meta connections |
+| POST | `/clinics` | `clinics:create` | Create clinic |
+| PUT | `/clinics/:id` | `clinics:update` | Update clinic settings |
+| DELETE | `/clinics/:id` | `clinics:delete` | Soft-delete clinic |
+| GET | `/clinics/:id/meta-connections` | `chats:config` | List WhatsApp/Instagram connections |
+| POST | `/clinics/:id/meta-connections` | `chats:config` | Add connection (encrypted token) |
+| GET | `/clinics/:id/meta-connections/:connId` | `chats:config` | Get connection |
+| PUT | `/clinics/:id/meta-connections/:connId` | `chats:config` | Update connection |
+| DELETE | `/clinics/:id/meta-connections/:connId` | `chats:config` | Disconnect |
+
+---
+
+## WhatsApp Chats (`/whatsapp`) — 13 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/whatsapp/chats` | `chats:read` / `chats:read_own` | List chats (search, assignedTo, status) |
+| GET | `/whatsapp/chats/:id` | `chats:read` | Get chat detail |
+| GET | `/whatsapp/chats/:id/messages` | `chats:read` | Get messages (decrypted, paginated) |
+| POST | `/whatsapp/chats/:id/takeover` | `chats:takeover` | Human takes over from AI |
+| POST | `/whatsapp/chats/:id/messages` | `chats:send` | Send human message |
+| POST | `/whatsapp/chats/:id/release` | `chats:takeover` | Release back to AI |
+| POST | `/whatsapp/chats/:id/resolve` | `chats:resolve` | Close session |
+| POST | `/whatsapp/chats/:id/assign` | `chats:assign` | Assign chat to user |
+| POST | `/whatsapp/chats/:id/unassign` | `chats:assign` | Remove assignment |
+| GET | `/whatsapp/stats` | `chats:read` | Chat/session statistics |
+| GET | `/whatsapp/blacklist` | `chats:config` | Get blacklisted numbers |
+| POST | `/whatsapp/blacklist` | `chats:config` | Add to blacklist |
+| DELETE | `/whatsapp/blacklist/:phone` | `chats:config` | Remove from blacklist |
+
+---
+
+## Availability Blocks (`/availability-blocks`) — 3 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/availability-blocks` | `appointments:read` | List blocks (`?clinicId&doctorId&from&to`) |
+| POST | `/availability-blocks` | `appointments:manage` | Create block (holiday/leave/break) |
+| DELETE | `/availability-blocks/:id` | `appointments:manage` | Delete block |
+
+---
+
+## Google Calendar (`/google-calendar`) — 5 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/google-calendar/auth-url` | `calendar:manage` | Get OAuth authorization URL |
+| GET | `/google-calendar/callback` | — | OAuth callback (browser redirect) |
+| POST | `/google-calendar/disconnect` | `calendar:manage` | Disconnect Google Calendar |
+| GET | `/google-calendar/calendars` | `calendar:read` | List available calendars |
+| PUT | `/google-calendar/calendar` | `calendar:manage` | Select calendar to use |
+
+---
+
+## Leads (`/leads`) — 5 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/leads` | `leads:read` | List leads (paginated, filterable) |
+| GET | `/leads/today` | `leads:read` | Last 24h leads |
+| GET | `/leads/export` | `leads:export` | Export CSV |
+| GET | `/leads/:id` | `leads:read` | Get lead detail |
+| PATCH | `/leads/:id` | `leads:update` | Update lead status |
+
+---
+
+## Calls (`/calls`) — 3 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/calls` | `calls:read` | List calls (paginated, filterable) |
+| GET | `/calls/stats` | `calls:read` | Call statistics |
+| GET | `/calls/:id` | `calls:read` | Call detail (transcript, summary) |
+
+---
+
+## Billing (`/billing`) — 5 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/billing/usage` | `billing:read` | Current period usage vs quotas |
+| GET | `/billing/daily-trend` | `billing:read` | Daily trend (last N days) |
+| GET | `/billing/snapshots` | `billing:read` | Past period snapshots |
+| GET | `/billing/history` | `billing:read` | Billing events (paginated) |
+| POST | `/billing/payments` | `billing:manage` | Record payment |
+
+---
+
+## Agents (`/agents`) — 5 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/agents` | `agents:read` | List agents |
+| GET | `/agents/:id` | `agents:read` | Get agent |
+| POST | `/agents` | `agents:manage` | Create agent |
+| PUT | `/agents/:id` | `agents:manage` | Update agent |
+| POST | `/agents/:id/toggle` | `agents:manage` | Toggle active |
+
+---
+
+## Phone Numbers (`/phone-numbers`) — 6 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/phone-numbers` | `phone_numbers:read` | List phone numbers |
+| GET | `/phone-numbers/:id` | `phone_numbers:read` | Get phone number |
+| POST | `/phone-numbers` | `phone_numbers:manage` | Create |
+| PUT | `/phone-numbers/:id` | `phone_numbers:manage` | Update |
+| PUT | `/phone-numbers/:id/schedule` | `phone_numbers:manage` | Update inbound schedule |
+| DELETE | `/phone-numbers/:id` | `phone_numbers:manage` | Delete |
+
+---
+
+## Outbound Campaigns (`/outbound-campaigns`) — 14 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/outbound-campaigns` | `campaigns:read` | List campaigns |
+| GET | `/outbound-campaigns/:id` | `campaigns:read` | Get campaign detail |
+| POST | `/outbound-campaigns` | `campaigns:manage` | Create campaign |
+| PUT | `/outbound-campaigns/:id` | `campaigns:manage` | Update (draft only) |
+| DELETE | `/outbound-campaigns/:id` | `campaigns:manage` | Delete (draft only) |
+| POST | `/outbound-campaigns/:id/entries` | `campaigns:manage` | Upload entries |
+| DELETE | `/outbound-campaigns/:id/entries` | `campaigns:manage` | Clear entries (draft only) |
+| POST | `/outbound-campaigns/:id/start` | `campaigns:manage` | Start campaign |
+| POST | `/outbound-campaigns/:id/pause` | `campaigns:manage` | Pause |
+| POST | `/outbound-campaigns/:id/resume` | `campaigns:manage` | Resume |
+| POST | `/outbound-campaigns/:id/stop` | `campaigns:manage` | Stop |
+| POST | `/outbound-campaigns/:id/retry` | `campaigns:manage` | Retry failed entries |
+| GET | `/outbound-campaigns/:id/results` | `campaigns:read` | Get results |
+| GET | `/outbound-campaigns/:id/export` | `campaigns:export` | Export results |
+
+---
+
+## Appointment Validation (`/appointment-validation`) — 8 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/appointment-validation` | `validation:read` | List batches |
+| GET | `/appointment-validation/:id` | `validation:read` | Get batch with entries |
+| POST | `/appointment-validation` | `validation:manage` | Create batch |
+| POST | `/appointment-validation/:id/submit` | `validation:manage` | Submit for processing |
+| POST | `/appointment-validation/:id/cancel` | `validation:manage` | Cancel batch |
+| POST | `/appointment-validation/:id/retry` | `validation:manage` | Retry failed entries |
+| POST | `/appointment-validation/:id/entries/:entryId/retry` | `validation:manage` | Retry single entry |
+| GET | `/appointment-validation/:id/export` | `validation:export` | Export results |
+
+---
+
+## Plans (`/plans`) — 4 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/plans` | — | List active plans |
+| GET | `/plans/:id` | — | Get plan |
+| POST | `/plans` | `platform:plans.manage` | Create plan (superadmin) |
+| PUT | `/plans/:id` | `platform:plans.manage` | Update plan (superadmin) |
+
+---
+
+## Tenants (`/tenants`) — 2 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/tenants/me` | — | Get current tenant |
+| PUT | `/tenants/me` | `tenant:update` | Update current tenant |
+
+---
+
+## Platform (`/platform`) — 6 endpoints (superadmin)
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/platform/tenants` | `platform:tenants.list` | List all tenants |
+| POST | `/platform/tenants` | `platform:tenants.create` | Create tenant + owner |
+| GET | `/platform/tenants/:id` | `platform:tenants.read` | Get tenant overview |
+| PUT | `/platform/tenants/:id` | `platform:tenants.update` | Update limits/features/plan |
+| PUT | `/platform/tenants/:id/deactivate` | `platform:tenants.update` | Deactivate tenant |
+| PUT | `/platform/tenants/:id/reactivate` | `platform:tenants.update` | Reactivate tenant |
+
+---
+
+## Admin (`/admin`) — 2 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/admin/system/health` | `platform:plans.manage` | System health (DB + Redis) |
+| GET | `/admin/system/usage` | `platform:plans.manage` | Global usage stats |
+
+---
+
+## Audit (`/audit-logs`) — 3 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/audit-logs` | `audit:read` | List audit logs (paginated) |
+| GET | `/audit-logs/entity/:entity/:entityId` | `audit:read` | Audit history for entity |
+| GET | `/audit-logs/user/:userId` | `audit:read` | Audit logs for user |
+
+---
+
+## Logs (`/admin/logs`) — 4 endpoints
+
+| Method | Path | Permission | Description |
+|---|---|---|---|
+| GET | `/admin/logs` | `audit:read` | List logs (paginated, filterable) |
+| GET | `/admin/logs/stats` | `audit:read` | Log count by level |
+| DELETE | `/admin/logs` | superadmin | Delete old logs |
+| GET | `/admin/logs/request/:requestId` | `audit:read` | Logs for a request |
+
+---
+
+## Webhooks (unauthenticated)
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| GET | `/webhooks/meta` | Verify token | Meta webhook verification |
+| POST | `/webhooks/meta` | Signature | Incoming WhatsApp/Instagram messages |
+| POST | `/webhooks/elevenlabs` | API key | ElevenLabs post-call webhook |
+| POST | `/webhooks/elevenlabs/tools/:toolName` | API key | ElevenLabs tool call during voice |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,305 @@
+# Portal Asistan 7/24 — Architecture & Codebase Reference
+
+## Overview
+
+Multi-tenant clinic management SaaS with integrated AI assistant. Built with NestJS + React.
+
+| Layer | Stack |
+|---|---|
+| **Backend** | NestJS 11 + Fastify + PostgreSQL + Prisma 7 + Redis + BullMQ |
+| **Frontend** | React 19 + Vite 8 + TypeScript + Tailwind v4 + shadcn/ui (Base UI) |
+| **Storage** | MinIO (S3-compatible) for files, thumbnails |
+| **Real-time** | Socket.IO gateway |
+| **Deployment** | Docker Compose (postgres, redis, minio, backend, nginx) |
+
+---
+
+## Backend — NestJS (`nestjs/`)
+
+### Stats
+
+| Metric | Count |
+|---|---|
+| Modules | 37 |
+| Controllers | 25 |
+| Services | 45 |
+| DTOs | 55 |
+| REST Endpoints | 174 |
+| Prisma Models | 45 |
+| Prisma Enums | 32 |
+
+### Module Map
+
+**Infrastructure**
+- `ConfigModule` — env vars
+- `DatabaseModule` — Prisma + PostgreSQL (PrismaPg adapter)
+- `RedisModule` — ioredis
+- `QueueModule` — BullMQ job processor
+- `EncryptionModule` — AES-256-GCM (5 keys for different data types)
+- `ImageModule` — sharp thumbnail generation
+
+**Auth & Identity**
+- `AuthModule` — JWT (opaque tokens in Redis), login/refresh/me/schedule
+- `TenantsModule` — multi-tenant isolation
+- `UsersModule` — CRUD, roles, doctor profiles, clinic assignments
+
+**Clinic Management**
+- `ClinicsModule` — clinic CRUD, meta connections, calendar connections
+- `PatientsModule` — 6 sub-services (medical history, notes, documents, photos, examinations)
+- `TreatmentsModule` — catalog + treatment plans with items
+- `AppointmentsModule` — scheduling, availability, reminders
+- `AvailabilityBlocksModule` — holidays, leaves, breaks (clinic + doctor)
+
+**Communication**
+- `WhatsAppModule` — chat management, session lifecycle, human takeover, assignment
+- `CallsModule` — voice call records
+- `LeadsModule` — lead pipeline
+- `AgentsModule` — AI agent configuration
+- `PhoneNumbersModule` — phone provisioning
+- `GoogleCalendarModule` — OAuth2 + FreeBusy API
+- `OutboundCampaignsModule` — batch outbound calling
+
+**Business**
+- `BillingModule` — usage events, payments, period snapshots
+- `PlansModule` — subscription plans with quotas
+- `AppointmentValidationModule` — batch confirmation calls
+
+**Platform (superadmin)**
+- `PlatformModule` — tenant CRUD, resource limits
+- `AdminModule` — system health, global usage stats
+
+### Request Pipeline
+
+```
+Fastify → Helmet → CORS → ValidationPipe → RequestContextInterceptor
+→ JwtAuthGuard → ClinicAccessGuard → PermissionsGuard → FeaturesGuard
+→ ThrottlerGuard (200/60s) → Controller → Service → Prisma/Redis/MinIO
+→ Socket.IO broadcast → Response
+```
+
+### Authentication Flow
+
+1. `POST /auth/login` → validates credentials → issues opaque access + refresh tokens
+2. Opaque token stored in Redis mapping to server-side JWT (client never sees JWT)
+3. `JwtAuthGuard` extracts token from `Authorization: Bearer` header or `?token=` query param
+4. Permissions computed: `customPermissions.length > 0 ? customPermissions : roleDefaults`
+5. Superadmin bypasses all permission checks
+
+### Roles & Permissions
+
+| Role | Key Permissions |
+|---|---|
+| `superadmin` | Bypasses all checks, platform management |
+| `owner` | Full CRM + settings + billing + audit |
+| `admin` | Full CRM + settings (no billing:manage) |
+| `doctor` | Patients, appointments, treatments, users:read |
+| `receptionist` | Patients, appointments, chats, leads, payments |
+| `sales` | chats:read_own, leads, patients:read/create |
+
+Custom per-user permissions override role defaults entirely when set.
+
+### Data Encryption
+
+5 separate AES-256-GCM keys (env vars):
+- `GOOGLE_TOKEN_ENCRYPTION_KEY` — Google OAuth refresh tokens
+- `META_TOKEN_ENCRYPTION_KEY` — Meta API access tokens
+- `MESSAGE_ENCRYPTION_KEY` — WhatsApp/chat messages
+- `PATIENT_PII_ENCRYPTION_KEY` — patient data, medical history, exam notes
+- `PATIENT_SUMMARY_ENCRYPTION_KEY` — AI-generated summaries
+
+### Key Database Models
+
+```
+Tenant → Clinic → Patient → Appointment
+                         → TreatmentPlan → TreatmentPlanItem
+                         → PatientDocument
+                         → PatientPhotoSet → PatientPhoto
+                         → ExaminationRecord
+                         → PatientMedicalHistory
+                         → PatientNote
+
+Clinic → ClinicCalendarConnection (working hours, Google Calendar)
+       → ClinicMetaConnection (WhatsApp/Instagram tokens)
+
+User → DoctorProfile (working hours, breaks, duration, holidays)
+     → UserClinicAssignment
+
+WhatsappChat → WhatsappSession → WhatsappMessage
+             → chat_assigned_to (User)
+
+AvailabilityBlock (clinic-wide or doctor-specific holidays/leaves/breaks)
+```
+
+---
+
+## Frontend — React (`frontend/`)
+
+### Stats
+
+| Metric | Count |
+|---|---|
+| Pages | 34 files across 21 directories |
+| Hooks | 12 custom hooks |
+| Components | 50 (33 shadcn + 17 shared) |
+| Routes | 26 |
+| i18n Keys | ~630 (Turkish + English) |
+
+### Tech Stack
+
+| Library | Version | Purpose |
+|---|---|---|
+| React | 19.2 | UI framework |
+| Vite | 8.0 | Build tool |
+| TanStack Query | 5.96 | Server state + caching |
+| Zustand | 5.0 | Client state (auth, UI) |
+| React Hook Form + Zod | 7.72 / 4.3 | Forms + validation |
+| Tailwind CSS | 4.2 | Styling |
+| shadcn/ui (Base UI) | latest | Component library |
+| Schedule-X | 4.3 | Calendar (week/day/month views) |
+| date-fns + TZDate | 4.1 | Date formatting with timezone |
+| i18next | 26.0 | Turkish + English |
+| Axios | 1.14 | HTTP client with interceptors |
+| Sonner | 2.0 | Toast notifications |
+
+### Route Map
+
+```
+/ ......................... Dashboard
+/login .................... Login page
+/patients ................. Patient list
+/patients/:id ............. Patient detail (8 tabs)
+/appointments ............. Appointment list + calendar toggle
+/calendar ................. Full-screen Schedule-X calendar
+/treatments ............... Treatment catalog
+/chats .................... WhatsApp inbox (sidebar + messages)
+/calls .................... Call history
+/leads .................... Lead pipeline
+/campaigns ................ Outbound campaigns
+/validation ............... Appointment validation batches
+/billing .................. Usage & payments
+/users .................... User list
+/users/:id/edit ........... User edit + permissions grid
+/users/:id/profile ........ Doctor profile (admin manages)
+/my-schedule .............. Doctor self-service schedule
+/clinics .................. Clinic list
+/clinics/:id/settings ..... Clinic settings + meta connections
+/agents ................... AI agent config
+/phone-numbers ............ Phone management
+/settings ................. General settings
+/audit .................... Audit trail
+/logs ..................... System logs
+/platform ................. Superadmin tenant management
+```
+
+### Custom Hooks
+
+| Hook | Endpoints Used |
+|---|---|
+| `use-patients` | patients CRUD, notes, documents, appointments |
+| `use-appointments` | appointments CRUD, stats, availability |
+| `use-treatments` | treatments CRUD, categories |
+| `use-treatment-plans` | plans + items CRUD |
+| `use-users` | users CRUD, doctor profiles, clinic assignments |
+| `use-clinics` | clinic list, timezone helper |
+| `use-clinic-detail` | clinic settings, meta connections, Google Calendar |
+| `use-chats` | chat list, messages, takeover, assign |
+| `use-examinations` | examination CRUD |
+| `use-medical-history` | medical history read/update |
+| `use-photo-sets` | photo set + photo CRUD |
+| `use-availability-blocks` | holiday/leave/break CRUD |
+
+### State Management
+
+- **Auth store** (`stores/auth.store.ts`) — user, tenant, permissions, login/logout/fetchMe
+- **UI store** (`stores/ui.store.ts`) — sidebar state, dark mode, language
+
+### Permission-Based UI
+
+- Sidebar items filtered by `user.permissions` at render time
+- `useHasPermission()` / `useHasRole()` hooks for component-level checks
+- Doctor role: auto-filtered to own data (calendar, appointments, schedule)
+- Sales role: only sees assigned chats (`chats:read_own`)
+- Superadmin: sees everything + Platform page
+
+### Timezone Handling
+
+- `useClinicTimezone()` hook reads from clinic settings (`clinic_timezone`)
+- Falls back to `Europe/Istanbul`
+- All date displays use `TZDate` from `@date-fns/tz`
+- Calendar component receives timezone prop
+- Backend stores UTC, frontend converts for display
+
+---
+
+## Deployment
+
+### Docker Compose (`docker-compose.nestjs.yml`)
+
+```
+┌─────────────────────────────────────────────┐
+│  External nginx (SSL) → 127.0.0.1:3021     │
+│                                              │
+│  ┌─────────────────────────────────────────┐ │
+│  │  frontend (nginx:alpine)  :80           │ │
+│  │    /api/* → proxy to backend:3005       │ │
+│  │    /*    → SPA (index.html)             │ │
+│  └────────────────┬────────────────────────┘ │
+│                   │                          │
+│  ┌────────────────▼────────────────────────┐ │
+│  │  backend (node:22-alpine)  :3005        │ │
+│  │    NestJS + Fastify                     │ │
+│  └──┬──────────┬──────────┬───────────────┘ │
+│     │          │          │                  │
+│  ┌──▼──┐  ┌───▼───┐  ┌──▼───┐              │
+│  │ pg  │  │ redis │  │ minio│              │
+│  │:5432│  │ :6379 │  │:9000 │              │
+│  └─────┘  └───────┘  └──────┘              │
+│  (all internal — no ports exposed to host)  │
+└─────────────────────────────────────────────┘
+```
+
+Only `127.0.0.1:3021` exposed. External nginx handles SSL termination.
+
+### Commands (`cd nestjs/`)
+
+```bash
+npm run docker:up        # Build and start everything
+npm run docker:down      # Stop all services
+npm run docker:logs      # Follow backend logs
+npm run docker:seed      # Seed database
+npm run docker:reset     # Wipe + re-seed database
+npm run docker:restart   # Restart backend only
+npm run docker:rebuild   # Rebuild backend + frontend
+npm run docker:ps        # Show container status
+```
+
+### Environment
+
+Backend reads from `nestjs/.env.docker`:
+- `FRONTEND_URL` — must match actual domain for CORS
+- `DATABASE_URL` — postgres internal hostname
+- `REDIS_URL` — redis internal hostname
+- `MINIO_ENDPOINT` — minio internal hostname
+- 5 encryption keys (generate with `openssl rand -hex 32`)
+- JWT secrets (generate with `openssl rand -hex 64`)
+
+---
+
+## Seed Data
+
+```bash
+npm run docker:seed
+```
+
+Creates 6 users across all roles:
+
+| Role | Email | Password |
+|---|---|---|
+| Superadmin | superadmin@portal.dev | superadmin123 |
+| Owner | admin@demo.com | demo123 |
+| Doctor 1 | mehmet@demo.com | doctor123 |
+| Doctor 2 | ayse@demo.com | doctor123 |
+| Receptionist | resepsiyon@demo.com | staff123 |
+| Sales | satis@demo.com | staff123 |
+
+Plus: 1 tenant (limits: 3 clinics, 10 users, 5 doctors, 1000 patients), 1 clinic with working hours + breaks, 5 treatments, 5 patients, 14 appointments.