DashboardSupportWelcome

👤 USER DOCS

Getting Started

Daily Operations

Shift Workspace & TasksPre-Shift SetupLine-Up CardsShift ReportsForms

Staff & Locations

Staff SchedulingManaging Locations

Oversight

Manager ReportsAnalyticsPre-Shift & Compliance

Incidents & Feedback

Incident ReportingAnonymous FeedbackMessages & Announcements

AI & Settings

AI ChatgearApp Settings

Administration

Dashboard & OnboardingAdmin

⚙️ DEVELOPER DOCS

Getting Started

Getting StartedDevelopmentDeployment Guide

Architecture

Architecture OverviewData FlowArchitecture Decision Records

Core Domain

Core DomainDatabase ReferenceLocations DomainAuth & RBACScheduling DomainReports DomainIncidents DomainNotifications DomainAudit Log & OptimizationDesign Audit Findings

Frontend

Frontend ArchitectureFormsLoading SkeletonsComponentsPWA & NotificationsimageScreenshots

API Reference

API Reference

Endpoints

POS Sales APIOptimization Data APISchedule Shifts APIEmployee Export APIReports APIIncidents APIAI Chat APIPush Notifications APIWebhooks APICron API

Contributing

ContributingcodeCode Examples

Security

Security & Compliance
Danvas IconDanvas
Danvas IconDanvas

Scheduling Domain

Technical architecture of the management scheduling system

Overview

The scheduling domain manages the planning and assignment of staff to restaurant shifts. It integrates with the compliance and shift task systems to ensure operational standards are met.

Database Schema

Scheduling data is organized around weekly schedules and individual shift assignments.

Management Schedules (management_schedules)

Represents a full week of shift planning for a team.

ColumnTypeDescription
teamIdtextReferences teams.id
weekOfdateThe start date of the week (typically Sunday)
statustextdraft, published
publishedAttimestampWhen the schedule was made public

Management Shifts (management_shifts)

Individual shift assignments within a schedule.

ColumnTypeDescription
scheduleIdtextReferences management_schedules.id
userIdtextReferences users.clerkId
dayOfWeekinteger0-6 (Sunday-Saturday)
shiftTypetextmorning, afternoon, evening
locationIdtextReferences locations.id

Auth & RBAC

Technical design of Clerk integration and Role-Based Access Control

Reports Domain

Technical deep dive into shift and manager report data models

On this page

OverviewDatabase SchemaManagement Schedules (management_schedules)Management Shifts (management_shifts)Shift Tasks SystemShift Task Definitions (shift_task_definitions)Shift Task Instances (shift_task_instances)Automated WorkflowsSchedule PublishingCode OrganizationRelated
roleOverridetextOptional role name if different from user default

Shift Tasks System

The scheduling domain also manages the definitions and instances of tasks assigned to shifts.

Shift Task Definitions (shift_task_definitions)

Recurring tasks defined by administrators.

ColumnTypeDescription
titletextTask name
frequencytextdaily, weekly, monthly
referenceImageUrltextExample photo of completed task

Shift Task Instances (shift_task_instances)

Specific tasks created for a user's shift.

ColumnTypeDescription
taskDefinitionIdtextReferences shift_task_definitions.id
datetextISO date (YYYY-MM-DD)
assignedTotextReferences users.clerkId
completedbooleanCompletion status
completionImageUrltextPhoto proof of completion

Automated Workflows

Schedule Publishing

When publishSchedule() is called:

  1. Compliance Generation: A record is created in the compliance table for every staff member scheduled, ensuring they file a shift report.
  2. Task Creation: shift_task_instances are generated based on the shift_task_definitions applicable to those shifts.
  3. Notifications: Push notifications are triggered via @repo/notifications to alert staff of their new schedule.

Code Organization

Scheduling logic is extracted into the @repo/schedules package (packages/schedules/), which exports:

  • Types: Schedule, ShiftShape, SaveShiftInput, PublishScheduleResult
  • Queries: getScheduleForWeek(), getStaffSchedule() — Drizzle queries for reading schedule data
  • Mutations: batchSaveShifts() — upsert-based save that preserves shift IDs via optional id field
  • Slack blocks: buildScheduleSlackBlocks() — formatted roster summary

The app's schedule builder actions (apps/app/.../schedule-builder/actions/) import from @repo/schedules rather than querying the database directly.

Related

Staff Scheduling Guide

Shift Reports Guide

Database Schema