Specialists Feature

Medical professionals who conduct appointments and complete clinical notes.

What this enables

Team management: Add doctors, therapists, and nurses to your clinic with their bio, photo, and professional credentials displayed to patients.

Scheduling profiles: Each specialist has their own availability (Mon 9am-5pm, Tue 2pm-8pm), timezone, and can work multiple clinics.

Public profiles: Patients see specialist names, titles, and bios when booking (e.g., "Dr. Smith, MD — Cardiologist").

Role-based access: Specialists with a login account can view their own patients and appointments, complete clinical notes, but see nothing from colleagues.

How it works

1. Admin adds a specialist: Name, title, timezone, photo, bio
2. Admin sets availability: "Available Mon-Fri 9-5 in Europe/Bucharest timezone"
3. Admin assigns to services: "Dr. Smith can do Cardiology consultations"
4. Admin optionally links user: Creates login credentials so specialist can access the app
5. Patients book: See Dr. Smith's profile, choose a time from her available slots
6. Specialist works: Logs in, completes appointment notes, sees only their own patients

---

Technical Reference

Overview

Specialists represent healthcare providers in the RestartiX Platform system. A specialist is a medical professional who can conduct appointments with patients. Each specialist can have one or more specialties, a scheduling profile for booking appointments, and an associated user account for login access.

What Specialists Are

Specialists are healthcare providers (doctors, therapists, nurses, etc.) who:

• Conduct appointments with patients
• Complete clinical forms (analysis, advice, prescriptions, reports)
• Have their own scheduling profiles (availability, timezone, working hours)
• Can be associated with one or more medical specialties
• May have a linked user account for system access

Relationship to Users

Specialists can optionally be linked to a user account via the user_id foreign key:

• With user account (user_id is set): The specialist can log into the system with role specialist. They can view and manage their own appointments, complete forms, and access patient records associated with their appointments.
• Without user account (user_id is NULL): The specialist exists in the system for scheduling and record-keeping purposes but cannot log in. Useful for external providers or staff who don't need system access.

The user_id link is stored on the specialists table and enforced with ON DELETE SET NULL (if the user is deleted, the specialist record remains but loses login access).

Scheduling Profile

Every specialist has an optional scheduling profile that enables public booking. The scheduling profile is stored directly on the specialists table:

Scheduling Columns (from scheduling/ feature)

• scheduling_timezone (VARCHAR, nullable): The specialist's IANA timezone (e.g., America/New_York, Europe/Bucharest). All scheduling calculations (weekly hours, overrides) are performed in this timezone. When NULL, the specialist has no scheduling profile and cannot be booked.
• scheduling_active (BOOLEAN, default TRUE): When false, the specialist does not appear in booking flows even if they have weekly hours configured.

Related Tables (from scheduling feature)

• specialist_weekly_hours: Recurring availability blocks by day of week (e.g., Mon 9:00-17:00, Tue 14:00-20:00). These are the specialist's DEFAULT hours.
• specialist_schedule_overrides: Date-specific exceptions (vacations, extra hours, holidays). Applies to ALL calendars the specialist is assigned to.
• calendar_specialists: Assignment to specific calendars with optional override_weekly_hours JSONB. When set, completely replaces the specialist's default hours for that calendar only (used for campaign calendars with limited availability).

Key concept: A specialist's weekly hours are their default availability. Individual calendars can override these hours for campaign/promotional purposes (e.g., "Free Wednesday Mornings 10-12").

See scheduling-config.md and ../scheduling/README.md for full details on the scheduling system.

Specialty Associations

Specialists can be associated with one or more specialties via the specialist_specialties junction table:

• Specialties define areas of medical practice (e.g., Cardiology, Dermatology, Orthopedics)
• A specialist can have multiple specialties
• A specialty can be associated with multiple specialists
• The junction table includes organization_id for direct RLS filtering (denormalized for performance)

This allows filtering specialists by specialty in the UI and helps patients find the right provider.

Organization Scoping

All specialists belong to an organization:

• The specialists table includes organization_id for direct RLS checks (no sub-queries needed)
• Each specialist can only be viewed and managed within their organization's context
• Multi-tenancy is enforced at the database level via Row-Level Security policies

Soft Delete

Specialists use soft delete (deleted_at timestamp) rather than hard delete:

• Reason: Medical record integrity (HIPAA compliance)
• When a specialist is "deleted", their deleted_at field is set to the current timestamp
• Historical appointments and clinical records remain intact and continue to reference the specialist
• Active specialists can be filtered with WHERE deleted_at IS NULL

Key Fields

Field	Type	Description
id	BIGINT	Internal primary key
organization_id	BIGINT	Organization this specialist belongs to (required, indexed)
user_id	BIGINT	Linked user account (nullable, unique)
name	TEXT	Specialist's full name (required)
title	TEXT	Professional title (e.g., "Cardiologist", "MD", "Licensed Therapist")
description	TEXT	Biography or professional description (markdown/HTML)
slug	TEXT	URL-friendly identifier (required, indexed)
signature_url	TEXT	S3 key for digital signature image
avatar_url	TEXT	S3 key for profile photo
scheduling_timezone	VARCHAR(64)	IANA timezone for scheduling (e.g., "Europe/Bucharest")
scheduling_active	BOOLEAN	Whether specialist accepts bookings (default true)
minicrm_name	TEXT	External miniCRM identifier (integration field)
deleted_at	TIMESTAMPTZ	Soft delete timestamp (nullable)
created_at	TIMESTAMPTZ	Creation timestamp (auto-set)
updated_at	TIMESTAMPTZ	Last update timestamp (auto-updated via trigger)

External References

• Database schema: See schema.sql for complete table definitions, indexes, and RLS policies
• API endpoints: See api.md for all specialist CRUD and query endpoints
• Scheduling configuration: See scheduling-config.md for weekly hours, overrides, and timezone handling
• Scheduling feature: See ../scheduling/ for full details on the availability engine and booking system