Appointments

Scheduling system for building inspections, customer meetings, and other project-related events. Supports proposal-based booking where customers pick time slots through the Portal.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts
Service	backend/src/services/appointment-service.ts
Portal Page	frontend/src/pages/portal/PortalAppointmentView.tsx
Queries	frontend/src/lib/queries/appointmentQueries.ts
Portal Queries	frontend/src/lib/queries/portalAppointmentQueries.ts

Database Tables

Table	Purpose
appointments	Main entity — date, time, type, status, location, assigned user, linked project
appointmentProposals	Time slot options sent to customers for selection

Key Fields

Field	Type	Notes
projectId	uuid FK	Parent project
buildingId	uuid FK	Associated building (inspection location)
assignedUserId	uuid FK	Staff member responsible
contactId	uuid FK	Customer contact for the appointment
type	enum	Appointment type (e.g., site inspection, consultation, handover)
status	enum	Lifecycle state (proposed, confirmed, completed, cancelled)
scheduledAt	timestamp	Confirmed date and time
notes	text	Internal notes

Proposal-Based Booking

1. Staff creates an appointment with multiple appointmentProposals (time slot options)
2. Customer receives a notification with a link to the Portal
3. Customer views proposals on PortalAppointmentView and selects a slot
4. Selected proposal becomes the confirmed scheduledAt; others are discarded
5. Both parties receive confirmation via Notifications

Workflow Integration

Appointments are created as part of Workflows tasks. Typical workflow tasks that generate appointments:

Task Type	Appointment Type
Site inspection	Building survey visit
Customer consultation	Advisory meeting
Results presentation	Final review meeting

The workflow task tracks the appointment status and can auto-advance when the appointment is completed.

Relationships

Appointment *──1 Project
Appointment *──1 Building
Appointment *──1 Users (assigned staff)
Appointment *──1 Contacts (customer)
Appointment 1──* AppointmentProposals
Appointment ──> Workflow Task (linked via workflow)

Frontend

• Internal view — appointments appear inline within Workflows task cards and on project detail pages
• Portal view — PortalAppointmentView.tsx provides the customer-facing proposal picker
• Queries — separate query files for internal (appointmentQueries.ts) and portal (portalAppointmentQueries.ts) contexts

Related Pages

Workflows | Projects | Buildings | Contacts | Portal | Notifications | Users | Service Layer Pattern