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

Notifications Domain

Technical architecture of Slack, Matrix, and Web Push integrations

Overview

The notifications domain manages multi-channel alerts and team communication. It leverages @repo/slack for operational summaries, @repo/matrix for real-time chat and AI interaction, and @repo/notifications for browser-level Web Push.

Slack Integration (@repo/slack)

Slack is the primary channel for operational visibility. We use the Slack Chat SDK (@slack/web-api) with bot tokens stored in the slack_installations table. Bot messages are delivered via chat.postMessage with Block Kit formatting.

Dynamic Routing

Routing is handled by notification-router.ts, which resolves bot tokens from the slack_configs and slack_installations tables based on:

  1. teamId (Required)
  2. formType (e.g., shift_report, incident, preshift)
  3. locationId (Optional location-specific override)

Template System

Slack message templates live in packages/slack/templates/ and include:

  • Shift reports — summary with location, ratings, and hero mention
  • Manager reports — daily operational summary
  • Incidents — severity-tagged alerts with status
  • Pre-shift briefings — staff goals with roles and POS targets
  • Labor variance alerts — multi-location threshold breaches
  • Schedule summaries — weekly roster overview
  • Anonymous feedback — category-tagged feedback with truncation

All templates enforce Slack's 2900-character section limit and 50-block message limit via truncate() helpers. Long fields are rendered in two-column section.fields blocks for compactness.

Incidents Domain

Technical lifecycle and audit trail of operational incidents

Audit Log & Optimization

Admin audit trail and sales/labor optimization tools

On this page

OverviewSlack Integration (@repo/slack)Dynamic RoutingTemplate SystemReliability PatternsMatrix Chat Integration (@repo/matrix)User SynchronizationAI Bot InteractionWeb Push Notifications (@repo/notifications)Email Notifications (@repo/email)Related

Reliability Patterns

  • Retry Logic: Failed deliveries are retried using an exponential backoff strategy (up to 3 attempts).
  • Asynchronous Processing: Notifications are queued in the notification_queue table and processed by the /api/notifications worker to prevent blocking the main request cycle.
  • Response Receipts: Bot messages include a Danvas context footer with timestamp for traceability.

Matrix Chat Integration (@repo/matrix)

Matrix provides a decentralized, encrypted chat infrastructure for teams.

User Synchronization

Users are automatically provisioned in Matrix when they join a team in Danvas.

  • Identity: Matrix IDs are deterministic: @clerk_id:matrix.canvasforge.io.
  • Encryption: Matrix access tokens are stored in the matrix_users table, encrypted with AES-256-GCM.

AI Bot Interaction

The Matrix bot listens for mentions and uses the Vercel AI SDK to respond. It has access to tools that query the Danvas database, allowing managers to ask questions like "What is the labor variance for today?" directly in chat.

Web Push Notifications (@repo/notifications)

Browser-native notifications used for high-urgency alerts.

  • Subscriptions: Stored in the push_subscriptions table.
  • VAPID Keys: Used for secure delivery to Google/Apple/Mozilla push services.
  • Service Worker: Handled by the Next.js PWA configuration (serwist).

Email Notifications (@repo/email)

Transactional emails delivered via Resend.

  • Templates: Built with React Email for consistent styling and type safety.
  • Provider: @repo/email wraps the Resend SDK with standardized logging and error handling.

Related

Database Schema

Reports Domain

API Reference