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

Reports Domain

Technical deep dive into shift and manager report data models

Overview

The reports domain handles the collection and storage of end-of-shift data from staff and daily operational summaries from managers. It includes automated Slack notifications, audit logging, and compliance tracking.

Database Schema

Reports are stored in two primary tables, separated by audience and purpose.

Server Reports (server_reports)

Captured at the end of each staff member's shift.

ColumnTypeDescription
userIdtextReferences users.clerkId
locationIdtextReferences locations.id
datetextISO date string (YYYY-MM-DD)
shifttextmorning, afternoon, evening
actualSalesnumericActual sales for the shift
goalSalesnumericTarget sales for the shift
fohRatinginteger0-5 rating
bohRatinginteger0-5 rating
incidentNotestextQualitative notes on incidents
herotextFree-text mention of a colleague

Manager Reports (manager_reports)

Captured daily by shift supervisors or general managers.

ColumnTypeDescription
totalSalesnumericCombined sales for the location/day
employeeReviews

Scheduling Domain

Technical architecture of the management scheduling system

Incidents Domain

Technical lifecycle and audit trail of operational incidents

On this page

OverviewDatabase SchemaServer Reports (server_reports)Manager Reports (manager_reports)Compliance TrackingCode OrganizationSlack Notification FlowAudit ComplianceWeekly MVP RecognitionRelated
jsonb
Array of objects: { name, role, review, photoUrl }
statustextdraft or published
publishedAttimestampWhen the report was finalized

Compliance Tracking

The compliance table tracks whether a user has filed their required report for a specific shift.

  • Record Creation: Compliance rows are created by the check-compliance cron job or when a user is assigned to a shift.
  • Completion: When submitReport() is called, the corresponding compliance row is updated: filed: true, filedAt: now().

Code Organization

Report logic is extracted into the @repo/reports package (packages/reports/), which exports shared types and utilities for report submission, compliance tracking, and audit logging. The app's report actions (apps/app/.../reports/actions.ts) import from @repo/reports.

Slack Notification Flow

Notifications are handled by @repo/slack using the Chat SDK bot (chat.postMessage) with Block Kit templates.

  1. Trigger: Server Action (submitReport or publishManagerReport) calls notifyReport().
  2. Routing: notification-router.ts queries slack_configs and slack_installations for the specific teamId and locationId.
  3. Template: templates/report.ts or templates/manager-report.ts generates the Block Kit JSON with truncation safeguards.
  4. Delivery: Bot posts to the configured Slack channel.

Audit Compliance

All report mutations wrap the database write and logAudit() call in a single atomic transaction. This ensures audit records are never dropped if the process crashes between the write and the log.

Weekly MVP Recognition

The aggregate-heroes cron job runs weekly to reward top performers.

  1. Query all server_reports from the past 7 days.
  2. Parse the hero field for staff names using regex.
  3. Count mentions per user.
  4. If mentions ≥ 3, create a congratulatory message in the messages table.

Related

Shift Reports Guide

Manager Reports Guide

Database Schema