Merge pull request 'feature/appointment' (#15) from feature/appointment into master

Reviewed-on: http://178.131.50.201:3000/admin/dyolink/pulls/15

backend/prisma/migrations/20260506163313_add_appointments/migration.sql

@@ -0,0 +1,26 @@
+-- CreateTable
+CREATE TABLE "appointments" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "patientId" TEXT NOT NULL,
+    "providerUserId" TEXT NOT NULL,
+    "startAt" TIMESTAMP(3) NOT NULL,
+    "endAt" TIMESTAMP(3) NOT NULL,
+    "purpose" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "appointments_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "appointments_organizationId_providerUserId_startAt_idx" ON "appointments"("organizationId", "providerUserId", "startAt");
+
+-- CreateIndex
+CREATE INDEX "appointments_organizationId_startAt_idx" ON "appointments"("organizationId", "startAt");
+
+-- AddForeignKey
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_organizationId_fkey" FOREIGN KEY ("organizationId") REFERENCES "organizations"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_patientId_fkey" FOREIGN KEY ("patientId") REFERENCES "patients"("id") ON DELETE CASCADE ON UPDATE CASCADE;

backend/prisma/schema.prisma

@@ -60,6 +60,7 @@ model Organization {
   sharedWithOthers OrganizationLink[] @relation("OrganizationA")
   sentOrganizationInvitations OrganizationInvitation[] @relation("OrganizationInvitationInviter")
   patients         Patient[]
+  appointments     Appointment[]
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -82,6 +83,7 @@ model Patient {
 
   organization Organization             @relation(fields: [organizationId], references: [id])
   treatments   PatientTreatmentHistory[]
+  appointments Appointment[]
 
   @@index([organizationId, createdAt])
   @@index([organizationId, lastName, firstName])
@@ -106,6 +108,26 @@ model PatientTreatmentHistory {
   @@map("patient_treatment_histories")
 }
 
+model Appointment {
+  id             String   @id @default(uuid())
+  organizationId String
+  patientId      String
+  providerUserId String
+  startAt        DateTime
+  endAt          DateTime
+  purpose        String
+
+  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  patient      Patient      @relation(fields: [patientId], references: [id], onDelete: Cascade)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([organizationId, providerUserId, startAt])
+  @@index([organizationId, startAt])
+  @@map("appointments")
+}
+
 model Plan {
   id       String @id @default(uuid())
   name     String @unique // "Solo", "Small", "Medium", "Large", "Enterprise"

backend/src/app.module.ts

@@ -9,6 +9,7 @@ import { PrismaModule } from '../prisma/prisma.module'; // ✅
 import { PatientsModule } from './modules/patients/patients.module';
 import { StaffModule } from './modules/staff/staff.module';
 import { OrganizationModule } from './modules/organization/organization.module';
+import { AppointmentsModule } from './modules/appointments/appointments.module';
 
 @Module({
   imports: [
@@ -19,6 +20,7 @@ import { OrganizationModule } from './modules/organization/organization.module';
     PrismaModule, // ✅ ADD THIS
     AuthModule,
     PatientsModule,
+    AppointmentsModule,
     StaffModule,
     OrganizationModule,
     AdminModule.forRoot(),

backend/src/modules/appointments/appointments.controller.ts

@@ -0,0 +1,51 @@
+import { Body, Controller, Delete, Get, Param, Post, Query, Req, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { AppointmentsService } from './appointments.service';
+import { CreateAppointmentDto } from './dto/create-appointment.dto';
+import { ListAppointmentsDto } from './dto/list-appointments.dto';
+
+@ApiTags('appointments')
+@ApiBearerAuth('JWT-auth')
+@UseGuards(JwtAuthGuard)
+@Controller('appointments')
+export class AppointmentsController {
+  constructor(private readonly appointmentsService: AppointmentsService) {}
+
+  @Get('column-providers')
+  @ApiOperation({
+    summary:
+      'Staff columns: active non-owner members with TAB_TREATMENT_EDIT. Owners are excluded. Requires TAB_APPOINTMENTS_READ or owner.',
+  })
+  columnProviders(@Req() req: { user: { id: string; organizationId?: string } }) {
+    const organizationId = this.appointmentsService.getOrganizationIdFromUser(req.user);
+    return this.appointmentsService.listColumnProviders(organizationId, req.user.id);
+  }
+
+  @Get()
+  @ApiOperation({ summary: 'List appointments intersecting a time range (requires TAB_APPOINTMENTS_READ or owner)' })
+  list(@Query() query: ListAppointmentsDto, @Req() req: { user: { id: string; organizationId?: string } }) {
+    const organizationId = this.appointmentsService.getOrganizationIdFromUser(req.user);
+    return this.appointmentsService.list(query, organizationId, req.user.id);
+  }
+
+  @Post()
+  @ApiOperation({ summary: 'Create appointment (requires TAB_APPOINTMENTS_EDIT or owner)' })
+  create(
+    @Body() dto: CreateAppointmentDto,
+    @Req() req: { user: { id: string; organizationId?: string } },
+  ) {
+    const organizationId = this.appointmentsService.getOrganizationIdFromUser(req.user);
+    return this.appointmentsService.create(dto, organizationId, req.user.id);
+  }
+
+  @Delete(':id')
+  @ApiOperation({ summary: 'Delete appointment (requires TAB_APPOINTMENTS_EDIT or owner)' })
+  remove(
+    @Param('id') id: string,
+    @Req() req: { user: { id: string; organizationId?: string } },
+  ) {
+    const organizationId = this.appointmentsService.getOrganizationIdFromUser(req.user);
+    return this.appointmentsService.remove(id, organizationId, req.user.id);
+  }
+}

backend/src/modules/appointments/appointments.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { PrismaService } from '../../../prisma/prisma.service';
+import { AppointmentsController } from './appointments.controller';
+import { AppointmentsService } from './appointments.service';
+
+@Module({
+  controllers: [AppointmentsController],
+  providers: [AppointmentsService, PrismaService],
+})
+export class AppointmentsModule {}

backend/src/modules/appointments/appointments.service.ts

@@ -0,0 +1,235 @@
+import {
+  BadRequestException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { PrismaService } from '../../../prisma/prisma.service';
+import { CreateAppointmentDto } from './dto/create-appointment.dto';
+import { ListAppointmentsDto } from './dto/list-appointments.dto';
+
+const MS_PER_DAY = 86_400_000;
+
+@Injectable()
+export class AppointmentsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  getOrganizationIdFromUser(user: { organizationId?: string }) {
+    if (!user?.organizationId) {
+      throw new BadRequestException('Organization is not selected');
+    }
+    return user.organizationId;
+  }
+
+  async listColumnProviders(organizationId: string, actorUserId: string) {
+    await this.assertCanViewAppointments(actorUserId, organizationId);
+
+    const members = await this.prisma.membership.findMany({
+      where: {
+        organizationId,
+        isOwner: false,
+        isActive: true,
+        permissions: {
+          some: {
+            permission: {
+              name: 'TAB_TREATMENT_EDIT',
+            },
+          },
+        },
+      },
+      include: {
+        user: { select: { id: true, name: true } },
+      },
+      orderBy: [{ createdAt: 'asc' }],
+    });
+
+    const data = members.map((m) => ({ userId: m.user.id, name: m.user.name }));
+
+    return { success: true, data };
+  }
+
+  async list(query: ListAppointmentsDto, organizationId: string, actorUserId: string) {
+    await this.assertCanViewAppointments(actorUserId, organizationId);
+
+    const from = new Date(query.from);
+    const to = new Date(query.to);
+
+    if (Number.isNaN(from.getTime()) || Number.isNaN(to.getTime())) {
+      throw new BadRequestException('Invalid date range');
+    }
+
+    if (to <= from) {
+      throw new BadRequestException('Range "to" must be after "from"');
+    }
+
+    const items = await this.prisma.appointment.findMany({
+      where: {
+        organizationId,
+        startAt: { lt: to },
+        endAt: { gt: from },
+      },
+      include: {
+        patient: {
+          select: { id: true, firstName: true, lastName: true, phone: true },
+        },
+      },
+      orderBy: [{ startAt: 'asc' }],
+    });
+
+    return { success: true, data: items };
+  }
+
+  async create(
+    dto: CreateAppointmentDto,
+    organizationId: string,
+    actorUserId: string,
+  ) {
+    await this.assertCanEditAppointments(actorUserId, organizationId);
+
+    const startAt = new Date(dto.startAt);
+    const endAt = new Date(dto.endAt);
+
+    if (Number.isNaN(startAt.getTime()) || Number.isNaN(endAt.getTime())) {
+      throw new BadRequestException('Invalid start or end time');
+    }
+
+    if (endAt <= startAt) {
+      throw new BadRequestException('End time must be after start time');
+    }
+
+    if (endAt.getTime() - startAt.getTime() > MS_PER_DAY) {
+      throw new BadRequestException('Appointment cannot span more than 24 hours');
+    }
+
+    const now = Date.now();
+    if (startAt.getTime() < now) {
+      throw new BadRequestException('Cannot schedule appointments in the past');
+    }
+
+    await this.ensurePatientInOrg(dto.patientId, organizationId);
+    await this.ensureProviderIsTreatmentEditor(dto.providerUserId, organizationId);
+
+    const overlap = await this.prisma.appointment.findFirst({
+      where: {
+        organizationId,
+        providerUserId: dto.providerUserId,
+        startAt: { lt: endAt },
+        endAt: { gt: startAt },
+      },
+      select: { id: true },
+    });
+
+    if (overlap) {
+      throw new BadRequestException('This time slot overlaps an existing appointment for that provider');
+    }
+
+    const appointment = await this.prisma.appointment.create({
+      data: {
+        organizationId,
+        patientId: dto.patientId,
+        providerUserId: dto.providerUserId,
+        startAt,
+        endAt,
+        purpose: dto.purpose,
+      },
+      include: {
+        patient: {
+          select: { id: true, firstName: true, lastName: true, phone: true },
+        },
+      },
+    });
+
+    return { success: true, data: appointment };
+  }
+
+  async remove(id: string, organizationId: string, actorUserId: string) {
+    await this.assertCanEditAppointments(actorUserId, organizationId);
+
+    const existing = await this.prisma.appointment.findFirst({
+      where: { id, organizationId },
+      select: { id: true },
+    });
+
+    if (!existing) {
+      throw new NotFoundException('Appointment not found');
+    }
+
+    await this.prisma.appointment.delete({
+      where: { id },
+    });
+
+    return { success: true };
+  }
+
+  private async assertCanViewAppointments(userId: string, organizationId: string) {
+    const m = await this.getMembership(userId, organizationId);
+    if (!m) {
+      throw new ForbiddenException('You are not a member of this organization');
+    }
+    if (m.isOwner) {
+      return;
+    }
+    const names = m.permissions.map((p) => p.permission.name);
+    if (names.includes('TAB_APPOINTMENTS_READ')) {
+      return;
+    }
+    if (names.includes('TAB_TREATMENT_EDIT')) {
+      return;
+    }
+    throw new ForbiddenException('You do not have access to appointments');
+  }
+
+  private async assertCanEditAppointments(userId: string, organizationId: string) {
+    const m = await this.getMembership(userId, organizationId);
+    if (!m) {
+      throw new ForbiddenException('You are not a member of this organization');
+    }
+    if (m.isOwner) {
+      return;
+    }
+    const names = m.permissions.map((p) => p.permission.name);
+    if (names.includes('TAB_APPOINTMENTS_EDIT')) {
+      return;
+    }
+    if (names.includes('TAB_TREATMENT_EDIT')) {
+      return;
+    }
+    throw new ForbiddenException('You cannot create or modify appointments');
+  }
+
+  private async ensureProviderIsTreatmentEditor(providerUserId: string, organizationId: string) {
+    const m = await this.getMembership(providerUserId, organizationId);
+    if (!m) {
+      throw new BadRequestException('Provider is not a member of this organization');
+    }
+    if (m.isOwner) {
+      throw new BadRequestException(
+        'Appointments must be assigned to staff with treatment access, not the organization owner',
+      );
+    }
+    if (!m.isActive) {
+      throw new BadRequestException('Provider is not an active staff member');
+    }
+    const names = m.permissions.map((p) => p.permission.name);
+    if (!names.includes('TAB_TREATMENT_EDIT')) {
+      throw new BadRequestException('Provider does not have treatment edit access');
+    }
+  }
+
+  private async ensurePatientInOrg(patientId: string, organizationId: string) {
+    const patient = await this.prisma.patient.findFirst({
+      where: { id: patientId, organizationId },
+      select: { id: true },
+    });
+    if (!patient) {
+      throw new NotFoundException('Patient not found');
+    }
+  }
+
+  private async getMembership(userId: string, organizationId: string) {
+    return this.prisma.membership.findFirst({
+      where: { userId, organizationId },
+      include: { permissions: { include: { permission: true } } },
+    });
+  }
+}

backend/src/modules/appointments/dto/create-appointment.dto.ts

@@ -0,0 +1,28 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsDateString, IsIn, IsUUID } from 'class-validator';
+
+const APPOINTMENT_PURPOSES = ['consultation', 'filling', 'endo', 'visit', 'hygiene'] as const;
+
+export type AppointmentPurpose = (typeof APPOINTMENT_PURPOSES)[number];
+
+export class CreateAppointmentDto {
+  @ApiProperty()
+  @IsUUID()
+  patientId: string;
+
+  @ApiProperty({ description: 'Staff user id (column provider)' })
+  @IsUUID()
+  providerUserId: string;
+
+  @ApiProperty({ example: '2026-05-06T09:15:00.000Z' })
+  @IsDateString()
+  startAt: string;
+
+  @ApiProperty({ example: '2026-05-06T09:45:00.000Z' })
+  @IsDateString()
+  endAt: string;
+
+  @ApiProperty({ enum: APPOINTMENT_PURPOSES })
+  @IsIn([...APPOINTMENT_PURPOSES])
+  purpose: AppointmentPurpose;
+}

backend/src/modules/appointments/dto/list-appointments.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsDateString } from 'class-validator';
+
+export class ListAppointmentsDto {
+  @ApiProperty({ description: 'Range start (ISO 8601), e.g. local midnight as instant' })
+  @IsDateString()
+  from: string;
+
+  @ApiProperty({ description: 'Range end (ISO 8601), e.g. next local midnight' })
+  @IsDateString()
+  to: string;
+}

frontend/src/app/(dashboard)/appointments/page.tsx

@@ -1,10 +1,349 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { appointmentsApi } from '@/lib/api/appointments';
+import { patientsApi } from '@/lib/api/patients';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { canEditAppointments, hasPermission } from '@/shared/permissions';
+import type { AppointmentColumnProvider, AppointmentRecord } from '@/types/appointment';
+import type { CreatePatientInput, Patient } from '@/types/patient';
+import { CreatePatientModal } from '@/components/ui/patient/CreatePatientModal';
+import { PatientSummaryCard } from '@/components/ui/patient/PatientSummaryCard';
+import { AppointmentBookingModal } from '@/components/ui/appointments/AppointmentBookingModal';
+import { AppointmentScheduleGrid } from '@/components/ui/appointments/AppointmentScheduleGrid';
+import { AppointmentsPatientSearch } from '@/components/ui/appointments/AppointmentsPatientSearch';
+import { AppointmentScheduleLegend } from '@/components/ui/appointments/AppointmentScheduleLegend';
+import { ScheduleDayPicker } from '@/components/ui/common/ScheduleDayPicker';
+import type { AppointmentPurpose } from '@/types/appointment';
+import { formatApiErrorMessage } from '@/lib/formatApiError';
+import { getLocalDayIsoRange, startOfLocalDay } from '@/lib/appointmentTime';
+
+const EMPTY_PATIENT_FORM: CreatePatientInput = {
+  firstName: '',
+  lastName: '',
+  phone: '',
+  email: '',
+};
+
 export default function AppointmentsPage() {
+  const { currentOrganization } = useAuth();
+  const [scheduleDate, setScheduleDate] = useState(() => startOfLocalDay(new Date()));
+
+  const [providers, setProviders] = useState<AppointmentColumnProvider[]>([]);
+  const [appointments, setAppointments] = useState<AppointmentRecord[]>([]);
+  const [loadingSchedule, setLoadingSchedule] = useState(false);
+  const [scheduleError, setScheduleError] = useState('');
+
+  const [search, setSearch] = useState('');
+  const [patients, setPatients] = useState<Patient[]>([]);
+  const [selectedPatient, setSelectedPatient] = useState<Patient | undefined>();
+  const [loadingPatients, setLoadingPatients] = useState(false);
+
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const [savingPatient, setSavingPatient] = useState(false);
+  const [patientForm, setPatientForm] = useState<CreatePatientInput>(EMPTY_PATIENT_FORM);
+
+  const [bookingOpen, setBookingOpen] = useState(false);
+  const [bookingHour, setBookingHour] = useState(9);
+  const [bookingProviderId, setBookingProviderId] = useState<string | null>(null);
+  const [bookingProviderName, setBookingProviderName] = useState('');
+  const [savingAppointment, setSavingAppointment] = useState(false);
+
+  const [toastError, setToastError] = useState('');
+  const [toastSuccess, setToastSuccess] = useState('');
+  const [toastInfo, setToastInfo] = useState('');
+
+  const canManageAppointments = canEditAppointments(currentOrganization);
+  const canEditPatients = hasPermission(currentOrganization, 'TAB_PATIENTS_EDIT');
+
+  const todayStart = useMemo(() => startOfLocalDay(new Date()), []);
+
+  const scheduleLoadGen = useRef(0);
+
+  const sortedPatients = useMemo(
+    () =>
+      [...patients].sort((a, b) =>
+        `${a.firstName} ${a.lastName}`.localeCompare(`${b.firstName} ${b.lastName}`),
+      ),
+    [patients],
+  );
+
+  const loadSchedule = useCallback(async () => {
+    if (!currentOrganization?.id) {
+      return;
+    }
+    const gen = ++scheduleLoadGen.current;
+    setLoadingSchedule(true);
+    setScheduleError('');
+    try {
+      const range = getLocalDayIsoRange(scheduleDate);
+      const [pRes, aRes] = await Promise.all([
+        appointmentsApi.columnProviders(),
+        appointmentsApi.list(range),
+      ]);
+      if (gen !== scheduleLoadGen.current) {
+        return;
+      }
+      setProviders(pRes.data);
+      setAppointments(aRes.data);
+    } catch (err: unknown) {
+      if (gen !== scheduleLoadGen.current) {
+        return;
+      }
+      setScheduleError(formatApiErrorMessage(err, 'Failed to load schedule.'));
+    } finally {
+      if (gen === scheduleLoadGen.current) {
+        setLoadingSchedule(false);
+      }
+    }
+  }, [currentOrganization?.id, scheduleDate]);
+
+  useEffect(() => {
+    void loadSchedule();
+  }, [loadSchedule]);
+
+  useEffect(() => {
+    const t = setTimeout(() => {
+      void loadPatientsSearch(search);
+    }, 300);
+    return () => clearTimeout(t);
+  }, [search]);
+
+  async function loadPatientsSearch(q: string) {
+    if (!currentOrganization) {
+      return;
+    }
+    setLoadingPatients(true);
+    try {
+      const response = await patientsApi.list({ q, page: 1, limit: 25 });
+      const items = response.data.items;
+      setPatients(items);
+      if (selectedPatient) {
+        const stillThere = items.find((p) => p.id === selectedPatient.id);
+        if (stillThere) {
+          setSelectedPatient(stillThere);
+        }
+      }
+    } catch {
+      setPatients([]);
+    } finally {
+      setLoadingPatients(false);
+    }
+  }
+
+  async function handleCreatePatient() {
+    setSavingPatient(true);
+    setToastError('');
+    setToastSuccess('');
+    try {
+      const response = await patientsApi.create(patientForm);
+      setIsCreateOpen(false);
+      setPatientForm(EMPTY_PATIENT_FORM);
+      await loadPatientsSearch(search);
+      setSelectedPatient(response.data);
+      setToastSuccess(`Patient ${response.data.firstName} ${response.data.lastName} was saved.`);
+    } catch (err: unknown) {
+      const message =
+        err && typeof err === 'object' && 'message' in err
+          ? String((err as { message: unknown }).message)
+          : 'Failed to save patient.';
+      setToastError(message);
+    } finally {
+      setSavingPatient(false);
+    }
+  }
+
+  function handleSlotClick(hour: number, providerUserId: string, providerName: string) {
+    if (!selectedPatient) {
+      setToastSuccess('');
+      setToastError('');
+      setToastInfo('Select a patient before booking.');
+      return;
+    }
+    setBookingHour(hour);
+    setBookingProviderId(providerUserId);
+    setBookingProviderName(providerName);
+    setBookingOpen(true);
+  }
+
+  async function handleSaveAppointment(payload: {
+    patientId: string;
+    providerUserId: string;
+    startAt: string;
+    endAt: string;
+    purpose: AppointmentPurpose;
+  }) {
+    setSavingAppointment(true);
+    setToastError('');
+    setToastSuccess('');
+    setToastInfo('');
+    try {
+      await appointmentsApi.create(payload);
+      setBookingOpen(false);
+      setToastSuccess('Appointment saved.');
+      await loadSchedule();
+    } catch (err: unknown) {
+      const message =
+        err && typeof err === 'object' && 'message' in err
+          ? String((err as { message: unknown }).message)
+          : 'Could not save appointment.';
+      setToastError(message);
+    } finally {
+      setSavingAppointment(false);
+    }
+  }
+
+  async function handleDeleteAppointment(id: string) {
+    if (!window.confirm('Remove this appointment?')) {
+      return;
+    }
+    setToastError('');
+    setToastSuccess('');
+    setToastInfo('');
+    try {
+      await appointmentsApi.remove(id);
+      setToastSuccess('Appointment removed.');
+      await loadSchedule();
+    } catch (err: unknown) {
+      const message =
+        err && typeof err === 'object' && 'message' in err
+          ? String((err as { message: unknown }).message)
+          : 'Could not delete appointment.';
+      setToastError(message);
+    }
+  }
+
+  useEffect(() => {
+    if (!toastSuccess) {
+      return;
+    }
+    const id = setTimeout(() => setToastSuccess(''), 3200);
+    return () => clearTimeout(id);
+  }, [toastSuccess]);
+
+  useEffect(() => {
+    if (!toastError) {
+      return;
+    }
+    const id = setTimeout(() => setToastError(''), 4000);
+    return () => clearTimeout(id);
+  }, [toastError]);
+
+  useEffect(() => {
+    if (!toastInfo) {
+      return;
+    }
+    const id = setTimeout(() => setToastInfo(''), 4000);
+    return () => clearTimeout(id);
+  }, [toastInfo]);
+
   return (
-    <div className="space-y-3">
+    <div className="relative space-y-6 pb-24">
+      <div className="grid grid-cols-1 xl:grid-cols-3 gap-6">
+        <div className="xl:col-span-1 space-y-4">
+          <div className="flex flex-col gap-1">
             <h1 className="text-2xl font-semibold text-text-primary">Appointments</h1>
             <p className="text-sm text-text-secondary">
-        Appointments module is coming soon.
+              Search a patient, pick a date, then click a time slot under a provider to book.
             </p>
           </div>
+
+          <AppointmentsPatientSearch
+            search={search}
+            onSearchChange={setSearch}
+            patients={sortedPatients}
+            selectedPatientId={selectedPatient?.id}
+            onSelectPatient={setSelectedPatient}
+            loading={loadingPatients}
+            canAddPatient={canEditPatients}
+            onAddPatient={() => {
+              if (!canEditPatients) {
+                return;
+              }
+              setIsCreateOpen(true);
+            }}
+          />
+          <PatientSummaryCard patient={selectedPatient} />
+        </div>
+
+        <div className="xl:col-span-2 space-y-4">
+          <AppointmentScheduleLegend />
+
+          <div className="flex flex-col sm:flex-row sm:items-end gap-4 sm:justify-between">
+            <ScheduleDayPicker
+              value={scheduleDate}
+              minDate={todayStart}
+              onChange={(d) => setScheduleDate(startOfLocalDay(d))}
+            />
+            {loadingSchedule && (
+              <p className="text-sm text-text-muted pb-2">Loading schedule…</p>
+            )}
+          </div>
+
+          {scheduleError && (
+            <div className="rounded-[var(--radius-sm)] border border-red-500/50 bg-red-500/10 px-3 py-2 text-sm text-red-300">
+              {scheduleError}
+            </div>
+          )}
+
+          <AppointmentScheduleGrid
+            day={scheduleDate}
+            providers={providers}
+            appointments={appointments}
+            canBook={canManageAppointments}
+            canDelete={canManageAppointments}
+            onDeleteAppointment={(id) => void handleDeleteAppointment(id)}
+            onSlotClick={(hour, uid, name) => handleSlotClick(hour, uid, name)}
+          />
+        </div>
+      </div>
+
+      <AppointmentBookingModal
+        open={bookingOpen}
+        scheduleDate={scheduleDate}
+        patient={selectedPatient}
+        providerUserId={bookingProviderId}
+        providerName={bookingProviderName}
+        initialHour={bookingHour}
+        onClose={() => setBookingOpen(false)}
+        onSubmit={handleSaveAppointment}
+        loading={savingAppointment}
+      />
+
+      {isCreateOpen && (
+        <div className="fixed inset-0 z-[60] flex items-center justify-center p-4 bg-black/55">
+          <CreatePatientModal
+            isOpen={isCreateOpen}
+            formData={patientForm}
+            onChange={(patch) => setPatientForm((prev) => ({ ...prev, ...patch }))}
+            onSubmit={() => void handleCreatePatient()}
+            onClose={() => setIsCreateOpen(false)}
+            loading={savingPatient}
+          />
+        </div>
+      )}
+
+      {(toastError || toastSuccess || toastInfo) && (
+        <div className="fixed bottom-4 left-4 right-4 z-[70] flex justify-center pointer-events-none">
+          <div className="pointer-events-auto w-full max-w-lg space-y-2">
+            {toastError && (
+              <div className="rounded-[var(--radius-sm)] border border-red-500/50 bg-red-500/10 px-3 py-2 text-sm text-red-300 shadow-lg">
+                {toastError}
+              </div>
+            )}
+            {toastInfo && (
+              <div className="rounded-[var(--radius-sm)] border border-amber-500/45 bg-amber-500/10 px-3 py-2 text-sm text-amber-100 shadow-lg">
+                {toastInfo}
+              </div>
+            )}
+            {toastSuccess && (
+              <div className="rounded-[var(--radius-sm)] border border-emerald-500/50 bg-emerald-500/10 px-3 py-2 text-sm text-emerald-300 shadow-lg">
+                {toastSuccess}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
   );
 }

frontend/src/app/(dashboard)/layout.tsx

@@ -7,6 +7,7 @@ import Sidebar from '@/components/ui/common/Sidebar';
 import { ThemeToggle } from '@/components/ui/common/ThemeToggle';
 import { DashboardAccountMenu } from '@/components/ui/dashboard/DashboardAccountMenu';
 import {
+  canAccessAppointmentsSection,
   firstAccessibleDashboardPath,
   getRequiredReadPermissionForPath,
   hasPermission,
@@ -32,9 +33,15 @@ export default function DashboardLayout({ children }: { children: React.ReactNod
     }
 
     const required = getRequiredReadPermissionForPath(pathname);
-    if (required && !hasPermission(currentOrganization, required)) {
+    if (required) {
+      const allowed =
+        hasPermission(currentOrganization, required) ||
+        (required === 'TAB_APPOINTMENTS_READ' &&
+          canAccessAppointmentsSection(currentOrganization));
+      if (!allowed) {
         router.replace(firstAccessibleDashboardPath(currentOrganization));
       }
+    }
   }, [isAuthReady, user, currentOrganization, router, pathname]);
 
   // ✅ LOADING ONLY FOR INITIAL LOAD

frontend/src/components/ui/appointments/AppointmentBookingModal.tsx

@@ -0,0 +1,199 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { X } from 'lucide-react';
+import { Button } from '@/components/ui/common/Button';
+import { Dropdown } from '@/components/ui/common/Dropdown';
+import { APPOINTMENT_PURPOSES, type AppointmentPurpose } from '@/types/appointment';
+import { APPOINTMENT_PURPOSE_LABEL } from '@/components/ui/appointments/appointmentPurposeStyles';
+import type { Patient } from '@/types/patient';
+import {
+  combineLocalDateAndTime,
+  formatTimeForInput,
+  isSameLocalCalendarDay,
+} from '@/lib/appointmentTime';
+
+interface AppointmentBookingModalProps {
+  open: boolean;
+  scheduleDate: Date;
+  patient: Patient | undefined;
+  providerUserId: string | null;
+  providerName: string;
+  initialHour: number;
+  onClose: () => void;
+  onSubmit: (payload: {
+    patientId: string;
+    providerUserId: string;
+    startAt: string;
+    endAt: string;
+    purpose: AppointmentPurpose;
+  }) => Promise<void>;
+  loading?: boolean;
+}
+
+export function AppointmentBookingModal({
+  open,
+  scheduleDate,
+  patient,
+  providerUserId,
+  providerName,
+  initialHour,
+  onClose,
+  onSubmit,
+  loading = false,
+}: AppointmentBookingModalProps) {
+  const [startTime, setStartTime] = useState('09:00');
+  const [endTime, setEndTime] = useState('10:00');
+  const [purpose, setPurpose] = useState<AppointmentPurpose>('consultation');
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const start = new Date(
+      scheduleDate.getFullYear(),
+      scheduleDate.getMonth(),
+      scheduleDate.getDate(),
+      initialHour,
+      0,
+      0,
+      0,
+    );
+    const end = new Date(
+      scheduleDate.getFullYear(),
+      scheduleDate.getMonth(),
+      scheduleDate.getDate(),
+      initialHour < 23 ? initialHour + 1 : 23,
+      initialHour < 23 ? 0 : 59,
+      0,
+      0,
+    );
+    setStartTime(formatTimeForInput(start));
+    setEndTime(formatTimeForInput(end));
+    setPurpose('consultation');
+    setError('');
+  }, [open, scheduleDate, initialHour]);
+
+  if (!open || !providerUserId) {
+    return null;
+  }
+
+  const inputClass =
+    'w-full rounded-[var(--radius-md)] border border-border bg-background-secondary/90 text-text-primary px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary/35';
+
+  async function handleSubmit() {
+    setError('');
+    if (!providerUserId) {
+      return;
+    }
+    if (!patient) {
+      setError('Select a patient first.');
+      return;
+    }
+
+    const startAt = combineLocalDateAndTime(scheduleDate, startTime);
+    const endAt = combineLocalDateAndTime(scheduleDate, endTime);
+
+    if (endAt <= startAt) {
+      setError('End time must be after start time.');
+      return;
+    }
+
+    const now = new Date();
+    if (isSameLocalCalendarDay(scheduleDate, now) && startAt.getTime() < now.getTime()) {
+      setError('Cannot schedule in the past.');
+      return;
+    }
+
+    await onSubmit({
+      patientId: patient.id,
+      providerUserId,
+      startAt: startAt.toISOString(),
+      endAt: endAt.toISOString(),
+      purpose,
+    });
+  }
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/55">
+      <div
+        className="surface-card w-full max-w-md p-5 space-y-4 shadow-xl"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="appointment-modal-title"
+      >
+        <div className="flex items-start justify-between gap-2">
+          <h2 id="appointment-modal-title" className="text-lg font-semibold text-text-primary pr-2">
+            New appointment
+          </h2>
+          <button
+            type="button"
+            onClick={onClose}
+            className="rounded-[var(--radius-sm)] p-1.5 text-text-muted hover:text-text-primary hover:bg-background-secondary/80 focus:outline-none focus:ring-2 focus:ring-primary/35"
+            aria-label="Close"
+          >
+            <X className="h-5 w-5 icon-flat" />
+          </button>
+        </div>
+
+        <p className="text-sm text-text-secondary">
+          Provider: <span className="text-text-primary font-medium">{providerName}</span>
+        </p>
+
+        <div>
+          <label className="block text-sm font-medium text-text-secondary mb-1">Patient</label>
+          <p className="text-sm text-text-primary rounded-[var(--radius-md)] border border-border bg-background-secondary/60 px-3 py-2">
+            {patient ? `${patient.firstName} ${patient.lastName}` : '—'}
+          </p>
+        </div>
+
+        <div className="grid grid-cols-2 gap-3">
+          <div>
+            <label className="block text-sm font-medium text-text-secondary mb-1">Start</label>
+            <input
+              type="time"
+              step={60}
+              className={inputClass}
+              value={startTime}
+              onChange={(e) => setStartTime(e.target.value)}
+            />
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-text-secondary mb-1">End</label>
+            <input
+              type="time"
+              step={60}
+              className={inputClass}
+              value={endTime}
+              onChange={(e) => setEndTime(e.target.value)}
+            />
+          </div>
+        </div>
+
+        <Dropdown
+          label="Purpose"
+          value={purpose}
+          onChange={(e) => setPurpose(e.target.value as AppointmentPurpose)}
+        >
+          {APPOINTMENT_PURPOSES.map((p) => (
+            <option key={p} value={p}>
+              {APPOINTMENT_PURPOSE_LABEL[p]}
+            </option>
+          ))}
+        </Dropdown>
+
+        {error && <p className="text-sm text-red-400">{error}</p>}
+
+        <div className="flex gap-2 justify-end">
+          <Button type="button" variant="ghost" onClick={onClose} disabled={loading}>
+            Cancel
+          </Button>
+          <Button type="button" variant="primary" onClick={() => void handleSubmit()} isLoading={loading}>
+            Save
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/appointments/AppointmentScheduleGrid.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import { Trash2 } from 'lucide-react';
+import type { AppointmentColumnProvider, AppointmentRecord } from '@/types/appointment';
+import { formatHourLabel } from '@/lib/appointmentTime';
+import { purposeDeleteIconClass, purposeStyle } from '@/components/ui/appointments/appointmentPurposeStyles';
+
+const HOUR_PX = 40;
+const HOURS = Array.from({ length: 24 }, (_, i) => i);
+
+function layoutBlock(apt: AppointmentRecord, day: Date): { top: string; height: string } | null {
+  const dayStart = new Date(day.getFullYear(), day.getMonth(), day.getDate(), 0, 0, 0, 0);
+  const dayEnd = new Date(day.getFullYear(), day.getMonth(), day.getDate() + 1, 0, 0, 0, 0);
+  const start = new Date(apt.startAt);
+  const end = new Date(apt.endAt);
+  const ms = dayEnd.getTime() - dayStart.getTime();
+  const clipStart = Math.max(start.getTime(), dayStart.getTime());
+  const clipEnd = Math.min(end.getTime(), dayEnd.getTime());
+  if (clipEnd <= clipStart) {
+    return null;
+  }
+  const top = ((clipStart - dayStart.getTime()) / ms) * 100;
+  const height = ((clipEnd - clipStart) / ms) * 100;
+  return { top: `${top}%`, height: `${height}%` };
+}
+
+interface AppointmentScheduleGridProps {
+  day: Date;
+  providers: AppointmentColumnProvider[];
+  appointments: AppointmentRecord[];
+  canBook: boolean;
+  canDelete?: boolean;
+  onDeleteAppointment?: (id: string) => void;
+  onSlotClick: (hour: number, providerUserId: string, providerName: string) => void;
+}
+
+export function AppointmentScheduleGrid({
+  day,
+  providers,
+  appointments,
+  canBook,
+  canDelete = false,
+  onDeleteAppointment,
+  onSlotClick,
+}: AppointmentScheduleGridProps) {
+  const gridHeight = HOURS.length * HOUR_PX;
+
+  if (providers.length === 0) {
+    return (
+      <div className="surface-card p-6 text-sm text-text-muted">
+        No providers available. Add staff with treatment edit access to see columns here.
+      </div>
+    );
+  }
+
+  return (
+    <div className="surface-card overflow-x-auto">
+      <div className="min-w-[640px]">
+        <div className="flex border-b border-border">
+          <div className="w-14 flex-shrink-0" />
+          {providers.map((p) => (
+            <div
+              key={p.userId}
+              className="flex-1 min-w-[130px] text-center text-sm font-medium text-text-primary py-2.5 px-1 border-l border-border"
+            >
+              {p.name}
+            </div>
+          ))}
+        </div>
+
+        <div className="flex">
+          <div className="w-14 flex-shrink-0 border-r border-border bg-background-secondary/40">
+            {HOURS.map((h) => (
+              <div
+                key={h}
+                className="text-[11px] text-text-muted flex items-start justify-end pr-1.5 pt-0.5 border-b border-border/50"
+                style={{ height: HOUR_PX }}
+              >
+                {formatHourLabel(h)}
+              </div>
+            ))}
+          </div>
+
+          <div className="flex-1 flex min-w-0">
+            {providers.map((p) => (
+              <div
+                key={p.userId}
+                className="flex-1 min-w-[130px] border-l border-border relative"
+                style={{ height: gridHeight }}
+              >
+                {HOURS.map((h) => {
+                  const slotDisabled = !canBook;
+                  return (
+                    <button
+                      key={h}
+                      type="button"
+                      disabled={slotDisabled}
+                      title={
+                        slotDisabled ? 'You cannot create appointments' : `Book ${formatHourLabel(h)}`
+                      }
+                      className={`absolute left-0 right-0 border-b border-border/50 transition-colors ${
+                        slotDisabled
+                          ? 'cursor-not-allowed opacity-50'
+                          : 'hover:bg-primary/8 cursor-pointer'
+                      }`}
+                      style={{ top: h * HOUR_PX, height: HOUR_PX }}
+                      onClick={() => onSlotClick(h, p.userId, p.name)}
+                    />
+                  );
+                })}
+
+                {appointments
+                  .filter((a) => a.providerUserId === p.userId)
+                  .map((apt) => {
+                    const pos = layoutBlock(apt, day);
+                    if (!pos) {
+                      return null;
+                    }
+                    return (
+                      <div
+                        key={apt.id}
+                        className={`absolute left-0.5 right-0.5 rounded-[var(--radius-sm)] border pointer-events-none z-10 flex flex-row items-center gap-1.5 px-1.5 py-1 min-h-[36px] ${purposeStyle(apt.purpose)}`}
+                        style={{ top: pos.top, height: pos.height, minHeight: 36 }}
+                      >
+                        <div className="pointer-events-none flex-1 min-w-0 overflow-hidden text-left">
+                          <p className="text-[11px] font-medium leading-tight truncate">
+                            {apt.patient.firstName} {apt.patient.lastName}
+                          </p>
+                          {apt.patient.phone && (
+                            <p className="text-[10px] opacity-90 truncate">{apt.patient.phone}</p>
+                          )}
+                        </div>
+                        {canDelete && onDeleteAppointment && (
+                          <button
+                            type="button"
+                            className="group pointer-events-auto shrink-0 self-center z-20 mr-2 ml-1 inline-flex cursor-pointer items-center justify-center rounded-[var(--radius-sm)] border-0 bg-transparent p-1 outline-none focus-visible:ring-2 focus-visible:ring-primary/35"
+                            aria-label="Delete appointment"
+                            title="Delete appointment"
+                            onClick={(e) => {
+                              e.stopPropagation();
+                              onDeleteAppointment(apt.id);
+                            }}
+                          >
+                            <Trash2 className={`w-4 h-4 ${purposeDeleteIconClass(apt.purpose)}`} />
+                          </button>
+                        )}
+                      </div>
+                    );
+                  })}
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/appointments/AppointmentScheduleLegend.tsx

@@ -0,0 +1,23 @@
+import {
+  APPOINTMENT_PURPOSE_LABEL,
+  APPOINTMENT_PURPOSE_LEGEND_SWATCH,
+} from '@/components/ui/appointments/appointmentPurposeStyles';
+import { APPOINTMENT_PURPOSES } from '@/types/appointment';
+
+export function AppointmentScheduleLegend() {
+  return (
+    <div className="surface-panel px-4 py-3">
+      <p className="text-xs font-medium text-text-secondary mb-2">Legend</p>
+      <div className="flex flex-wrap gap-3">
+        {APPOINTMENT_PURPOSES.map((p) => (
+          <div key={p} className="flex items-center gap-1.5 text-xs text-text-secondary">
+            <span
+              className={`inline-block h-3 w-3 rounded-sm border ${APPOINTMENT_PURPOSE_LEGEND_SWATCH[p]}`}
+            />
+            {APPOINTMENT_PURPOSE_LABEL[p]}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/appointments/AppointmentsPatientSearch.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { Search } from 'lucide-react';
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
+import type { Patient } from '@/types/patient';
+
+interface AppointmentsPatientSearchProps {
+  search: string;
+  onSearchChange: (value: string) => void;
+  patients: Patient[];
+  selectedPatientId?: string;
+  onSelectPatient: (patient: Patient) => void;
+  loading?: boolean;
+  canAddPatient: boolean;
+  onAddPatient: () => void;
+}
+
+export function AppointmentsPatientSearch({
+  search,
+  onSearchChange,
+  patients,
+  selectedPatientId,
+  onSelectPatient,
+  loading = false,
+  canAddPatient,
+  onAddPatient,
+}: AppointmentsPatientSearchProps) {
+  const trimmed = search.trim();
+  const showAddForEmptyResults =
+    trimmed.length > 0 && !loading && patients.length === 0;
+
+  return (
+    <div className="surface-card p-4 space-y-4">
+      <div className="flex flex-col sm:flex-row gap-3 sm:items-center">
+        <div className="flex-1">
+          <Input
+            placeholder="Search existing patients"
+            value={search}
+            onChange={(e) => onSearchChange(e.target.value)}
+            icon={<Search className="h-4 w-4 icon-flat" />}
+          />
+        </div>
+        {showAddForEmptyResults && (
+          <Button
+            type="button"
+            variant="primary"
+            disabled={!canAddPatient}
+            onClick={onAddPatient}
+            title={!canAddPatient ? 'You do not have permission to add patients.' : undefined}
+          >
+            + Add New Patient
+          </Button>
+        )}
+      </div>
+
+      <div className="space-y-2 max-h-72 overflow-y-auto">
+        {loading && <p className="text-sm text-text-muted">Searching…</p>}
+
+        {!loading && trimmed.length === 0 && (
+          <p className="text-sm text-text-muted">Type to search patients by name, phone, or email.</p>
+        )}
+
+        {patients.map((patient) => {
+          const isSelected = selectedPatientId === patient.id;
+          return (
+            <button
+              key={patient.id}
+              type="button"
+              onClick={() => onSelectPatient(patient)}
+              className={`w-full text-left rounded-[var(--radius-sm)] border px-3 py-2 transition-colors ${
+                isSelected
+                  ? 'bg-primary-soft border-primary/60'
+                  : 'border-border/60 hover:bg-background-card/70'
+              }`}
+            >
+              <p className="text-sm font-medium text-text-primary">
+                {patient.firstName} {patient.lastName}
+              </p>
+              <p className="text-xs text-text-muted">{patient.phone || patient.email || 'No contact'}</p>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/appointments/appointmentPurposeStyles.ts

@@ -0,0 +1,45 @@
+import type { AppointmentPurpose } from '@/types/appointment';
+
+export const APPOINTMENT_PURPOSE_LABEL: Record<AppointmentPurpose, string> = {
+  consultation: 'Consultation',
+  filling: 'Filling',
+  endo: 'Endo',
+  visit: 'Visit',
+  hygiene: 'Hygiene',
+};
+
+/** Background + border for blocks / legend (matches reference palette). */
+export const APPOINTMENT_PURPOSE_STYLES: Record<AppointmentPurpose, string> = {
+  consultation: 'bg-violet-500/25 border-violet-400/50 text-violet-100',
+  filling: 'bg-orange-500/25 border-orange-400/50 text-orange-100',
+  endo: 'bg-red-500/25 border-red-400/50 text-red-100',
+  visit: 'bg-sky-500/25 border-sky-400/50 text-sky-100',
+  hygiene: 'bg-lime-500/20 border-lime-400/45 text-lime-100',
+};
+
+export function purposeStyle(purpose: string): string {
+  const p = purpose as AppointmentPurpose;
+  return APPOINTMENT_PURPOSE_STYLES[p] ?? 'bg-surface-elevated border-border text-text-secondary';
+}
+
+/** Trash icon — legend hues; `!` overrides global `.lucide { color: var(--color-icon) }`. */
+export function purposeDeleteIconClass(purpose: string): string {
+  const p = purpose as AppointmentPurpose;
+  const map: Record<AppointmentPurpose, string> = {
+    consultation: '!text-violet-400 group-hover:!text-violet-300',
+    filling: '!text-orange-400 group-hover:!text-orange-300',
+    endo: '!text-red-400 group-hover:!text-red-300',
+    visit: '!text-sky-400 group-hover:!text-sky-300',
+    hygiene: '!text-lime-600 group-hover:!text-lime-500',
+  };
+  return map[p] ?? '!text-text-muted group-hover:!text-text-secondary';
+}
+
+/** Small swatch for legend (background + border only). */
+export const APPOINTMENT_PURPOSE_LEGEND_SWATCH: Record<AppointmentPurpose, string> = {
+  consultation: 'bg-violet-500/85 border-violet-400/75',
+  filling: 'bg-orange-500/85 border-orange-400/75',
+  endo: 'bg-red-500/85 border-red-400/75',
+  visit: 'bg-sky-500/85 border-sky-400/75',
+  hygiene: 'bg-lime-500/80 border-lime-400/70',
+};

frontend/src/components/ui/common/Dropdown.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import { ChevronDown } from 'lucide-react';
+import React, { forwardRef } from 'react';
+
+interface DropdownProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
+  label?: string;
+  error?: string;
+}
+
+export const Dropdown = forwardRef<HTMLSelectElement, DropdownProps>(
+  ({ label, error, className = '', id, children, ...props }, ref) => {
+    const selectId = id || `dropdown-${Math.random().toString(36).slice(2, 9)}`;
+
+    return (
+      <div className="w-full">
+        {label && (
+          <label
+            htmlFor={selectId}
+            className="block text-sm font-medium text-text-secondary mb-1"
+          >
+            {label}
+          </label>
+        )}
+
+        <div className="relative">
+          <select
+            ref={ref}
+            id={selectId}
+            className={`
+              w-full appearance-none rounded-[var(--radius-md)] border
+              ${error ? 'border-red-500' : 'border-border'}
+              bg-background-secondary/90 text-text-primary
+
+              pl-4 pr-14 py-2 text-sm
+
+              focus:outline-none focus:ring-2 focus:ring-primary/35 focus:border-border-strong
+
+              disabled:opacity-50 disabled:cursor-not-allowed
+
+              transition-all duration-200 shadow-[inset_0_1px_0_rgba(255,255,255,0.02)]
+
+              ${className}
+            `}
+            {...props}
+          >
+            {children}
+          </select>
+
+          <div
+            className="pointer-events-none absolute inset-y-0 right-5 flex items-center text-text-muted"
+            aria-hidden
+          >
+            <ChevronDown className="h-4 w-4 icon-flat" />
+          </div>
+        </div>
+
+        {error && (
+          <p className="mt-1 text-sm text-red-500">
+            {error}
+          </p>
+        )}
+      </div>
+    );
+  },
+);
+
+Dropdown.displayName = 'Dropdown';

frontend/src/components/ui/common/ScheduleDayPicker.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { addCalendarDays, compareLocalDayStart } from '@/lib/appointmentTime';
+
+interface ScheduleDayPickerProps {
+  value: Date;
+  onChange: (day: Date) => void;
+  /** Inclusive minimum calendar day (typically today at local midnight). */
+  minDate: Date;
+  label?: string;
+}
+
+export function ScheduleDayPicker({ value, onChange, minDate, label = 'Schedule date' }: ScheduleDayPickerProps) {
+  const canGoPrev = compareLocalDayStart(value, minDate) > 0;
+
+  const labelText = value.toLocaleDateString(undefined, {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+
+  return (
+    <div className="w-full max-w-md">
+      <p className="text-sm font-medium text-text-secondary mb-2">{label}</p>
+      <div className="flex items-center gap-1 rounded-[var(--radius-md)] border border-border bg-background-secondary/90 px-1 py-1 shadow-[inset_0_1px_0_rgba(255,255,255,0.02)]">
+        <button
+          type="button"
+          disabled={!canGoPrev}
+          onClick={() => onChange(addCalendarDays(value, -1))}
+          className="shrink-0 rounded-[var(--radius-sm)] p-2 text-text-muted hover:text-text-primary hover:bg-background-card/80 disabled:opacity-35 disabled:pointer-events-none focus:outline-none focus:ring-2 focus:ring-primary/35"
+          aria-label="Previous day"
+        >
+          <ChevronLeft className="h-4 w-4 icon-flat" />
+        </button>
+        <div className="flex-1 min-w-0 text-center text-sm font-medium text-text-primary tabular-nums px-2 py-1.5">
+          {labelText}
+        </div>
+        <button
+          type="button"
+          onClick={() => onChange(addCalendarDays(value, 1))}
+          className="shrink-0 rounded-[var(--radius-sm)] p-2 text-text-muted hover:text-text-primary hover:bg-background-card/80 focus:outline-none focus:ring-2 focus:ring-primary/35"
+          aria-label="Next day"
+        >
+          <ChevronRight className="h-4 w-4 icon-flat" />
+        </button>
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/common/Sidebar.tsx

@@ -13,7 +13,7 @@ import {
   CreditCard,
 } from 'lucide-react';
 import { useAuth } from '@/lib/hooks/useAuth';
-import { canViewTab } from '@/shared/permissions';
+import { canAccessAppointmentsSection, canViewTab } from '@/shared/permissions';
 
 const menu = [
   { name: 'Today', path: '/today', icon: LayoutDashboard, read: 'TAB_TODAY_READ' as const },
@@ -47,7 +47,12 @@ function Sidebar() {
         menu[5],
         menu[6],
       ];
-      return withCounterpartTab.filter((item) => canViewTab(currentOrganization, item.read));
+      return withCounterpartTab.filter((item) => {
+        if (item.path === '/appointments') {
+          return canAccessAppointmentsSection(currentOrganization);
+        }
+        return canViewTab(currentOrganization, item.read);
+      });
     },
     [counterpartLabel, currentOrganization],
   );

frontend/src/lib/api/appointments.ts

@@ -0,0 +1,32 @@
+import { apiClient } from './client';
+import type { AppointmentColumnProvider, AppointmentRecord } from '@/types/appointment';
+
+export interface CreateAppointmentBody {
+  patientId: string;
+  providerUserId: string;
+  startAt: string;
+  endAt: string;
+  purpose: string;
+}
+
+export const appointmentsApi = {
+  columnProviders: async (): Promise<{ success: boolean; data: AppointmentColumnProvider[] }> => {
+    const response = await apiClient.get('/appointments/column-providers');
+    return response.data;
+  },
+
+  list: async (params: { from: string; to: string }): Promise<{ success: boolean; data: AppointmentRecord[] }> => {
+    const response = await apiClient.get('/appointments', { params });
+    return response.data;
+  },
+
+  create: async (body: CreateAppointmentBody): Promise<{ success: boolean; data: AppointmentRecord }> => {
+    const response = await apiClient.post('/appointments', body);
+    return response.data;
+  },
+
+  remove: async (id: string): Promise<{ success: boolean }> => {
+    const response = await apiClient.delete(`/appointments/${id}`);
+    return response.data;
+  },
+};

frontend/src/lib/appointmentTime.ts

@@ -0,0 +1,63 @@
+/** Normalize to local midnight; invalid input falls back to today. */
+export function startOfLocalDay(d: Date): Date {
+  if (Number.isNaN(d.getTime())) {
+    const t = new Date();
+    return new Date(t.getFullYear(), t.getMonth(), t.getDate(), 0, 0, 0, 0);
+  }
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);
+}
+
+/** Local calendar bounds for a date (browser timezone). */
+export function getLocalDayIsoRange(day: Date): { from: string; to: string } {
+  const start = startOfLocalDay(day);
+  const end = new Date(start.getFullYear(), start.getMonth(), start.getDate() + 1, 0, 0, 0, 0);
+  return { from: start.toISOString(), to: end.toISOString() };
+}
+
+export function toDateInputValue(d: Date): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+export function parseDateInput(value: string): Date {
+  const [y, m, d] = value.split('-').map(Number);
+  return new Date(y, m - 1, d, 0, 0, 0, 0);
+}
+
+export function combineLocalDateAndTime(day: Date, timeHHmm: string): Date {
+  const [h, min] = timeHHmm.split(':').map(Number);
+  return new Date(day.getFullYear(), day.getMonth(), day.getDate(), h, min, 0, 0);
+}
+
+export function formatTimeForInput(d: Date): string {
+  const h = String(d.getHours()).padStart(2, '0');
+  const m = String(d.getMinutes()).padStart(2, '0');
+  return `${h}:${m}`;
+}
+
+export function isSameLocalCalendarDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}
+
+export function formatHourLabel(hour: number): string {
+  const d = new Date(2000, 0, 1, hour, 0, 0, 0);
+  return d.toLocaleTimeString(undefined, { hour: 'numeric', hour12: true });
+}
+
+/** Local midnight + delta calendar days. */
+export function addCalendarDays(day: Date, delta: number): Date {
+  return new Date(day.getFullYear(), day.getMonth(), day.getDate() + delta, 0, 0, 0, 0);
+}
+
+/** Compare two calendar days at local midnight (ordering by date only). */
+export function compareLocalDayStart(a: Date, b: Date): number {
+  const ta = new Date(a.getFullYear(), a.getMonth(), a.getDate()).getTime();
+  const tb = new Date(b.getFullYear(), b.getMonth(), b.getDate()).getTime();
+  return ta - tb;
+}

frontend/src/lib/formatApiError.ts

@@ -0,0 +1,12 @@
+export function formatApiErrorMessage(err: unknown, fallback: string): string {
+  if (err && typeof err === 'object' && 'message' in err) {
+    const m = (err as { message: unknown }).message;
+    if (Array.isArray(m)) {
+      return m.filter(Boolean).join(', ');
+    }
+    if (typeof m === 'string' && m.trim()) {
+      return m;
+    }
+  }
+  return fallback;
+}

frontend/src/shared/permissions.ts

@@ -48,3 +48,35 @@ export function canViewStaff(org: Organization | null): boolean {
     hasPermission(org, 'TAB_STAFF_READ') || hasPermission(org, 'TAB_STAFF_EDIT')
   );
 }
+
+/**
+ * Create/delete/book slots: owners, appointment editors, or treatment editors (schedule columns).
+ * Aligns with backend appointment mutations.
+ */
+export function canEditAppointments(org: Organization | null): boolean {
+  if (!org) {
+    return false;
+  }
+  if (org.isOwner) {
+    return true;
+  }
+  return (
+    hasPermission(org, 'TAB_APPOINTMENTS_EDIT') ||
+    hasPermission(org, 'TAB_TREATMENT_EDIT')
+  );
+}
+
+/** Route + sidebar: view appointments page if user can read appointments or manage treatment (column staff). */
+export function canAccessAppointmentsSection(org: Organization | null): boolean {
+  if (!org) {
+    return false;
+  }
+  if (org.isOwner) {
+    return true;
+  }
+  return (
+    hasPermission(org, 'TAB_APPOINTMENTS_READ') ||
+    hasPermission(org, 'TAB_APPOINTMENTS_EDIT') ||
+    hasPermission(org, 'TAB_TREATMENT_EDIT')
+  );
+}

frontend/src/types/appointment.ts

@@ -0,0 +1,27 @@
+import type { Patient } from './patient';
+
+export const APPOINTMENT_PURPOSES = [
+  'consultation',
+  'filling',
+  'endo',
+  'visit',
+  'hygiene',
+] as const;
+
+export type AppointmentPurpose = (typeof APPOINTMENT_PURPOSES)[number];
+
+export interface AppointmentColumnProvider {
+  userId: string;
+  name: string;
+}
+
+export interface AppointmentRecord {
+  id: string;
+  organizationId: string;
+  patientId: string;
+  providerUserId: string;
+  startAt: string;
+  endAt: string;
+  purpose: string;
+  patient: Pick<Patient, 'id' | 'firstName' | 'lastName' | 'phone'>;
+}