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

Data Flow

How data moves through Danvas

Understanding data flow is critical for debugging and feature development. This diagram shows the primary paths for authenticated requests through Danvas.

System Data Flow

flowchart TD
    subgraph Auth["Authentication"]
        CLERK[Clerk Auth<br/>OAuth/SSO/Webhooks]
    end

    subgraph Frontend["Frontend Layer"]
        APP[apps/app<br/>Next.js 16]
        WEB[apps/web<br/>Marketing]
    end

    subgraph Backend["Backend Packages"]
        AUTH[@repo/auth<br/>User provisioning<br/>Access control]
        DB[@repo/database<br/>Drizzle ORM<br/>PostgreSQL]
        ANALYTICS[@repo/analytics<br/>PostHog client<br/>External API]
        MATRIX[@repo/matrix<br/>Matrix Synapse<br/>Bot client]

Architecture Overview

High-level architecture of the Danvas platform

Architecture Decision Records

Significant architectural decisions made during development

On this page

System Data FlowRequest Lifecycle1. Authenticated Page Load2. Server Action Mutation3. Webhook ProcessingKey PatternsMulti-Tenant IsolationCircuit BreakerCache StrategiesRelated Files
SLACK[@repo/slack<br/>Slack API<br/>Block Kit]
NOTIF[@repo/notifications<br/>Web Push]
end
subgraph External["External Services"]
NEON[(Neon PostgreSQL)]
TOAST[Toast POS API]
MATRIX_SV[Matrix Synapse]
SLACK_API[Slack API]
PUSH[Web Push Service]
POSTHOG[PostHog]
end
CLERK --> AUTH
AUTH --> DB
DB --> NEON
APP --> AUTH
APP --> DB
APP --> ANALYTICS
ANALYTICS --> TOAST
APP --> MATRIX
MATRIX --> MATRIX_SV
APP --> SLACK
SLACK --> SLACK_API
APP --> NOTIF
NOTIF --> PUSH
APP --> POSTHOG

Request Lifecycle

1. Authenticated Page Load

sequenceDiagram
    participant User
    participant NextJS
    participant Auth
    participant DB

    User->>NextJS: Request protected page
    NextJS->>Auth: getUserAuth()
    Auth->>CLERK: Verify session
    Auth->>DB: Lookup/create user
    Auth-->>NextJS: User object
    NextJS->>DB: Query filtered by teamId
    NextJS-->>User: Rendered page

2. Server Action Mutation

sequenceDiagram
    participant User
    participant Action
    participant Auth
    participant DB
    participant Audit
    participant Slack

    User->>Action: Submit form
    Action->>Auth: requireAdmin()
    Auth-->>Action: Verified user
    Action->>DB: Begin transaction
    Action->>DB: Write data
    Action->>Audit: logAudit()
    Action->>DB: Commit
    Action->>Slack: Send notification
    Action-->>User: Success response

3. Webhook Processing

sequenceDiagram
    participant Service
    participant API
    participant Webhook
    participant Auth
    participant DB
    participant Matrix

    Service->>API: POST /webhooks/clerk
    API->>Webhook: verify() signature
    API->>Auth: provisionUser()
    Auth->>DB: Create/update user
    API->>Matrix: provisionMatrixUser()
    API-->>Service: { received: true }

Key Patterns

Multi-Tenant Isolation

All queries filter by teamId (Clerk organization ID):

// Always include team filter
const posts = await db.query.posts.findMany({
  where: eq(posts.teamId, user.teamId)
});

Circuit Breaker

The analytics clients use circuit breakers:

  • Threshold: 5 failures
  • Timeout: 60 seconds
  • States: Closed → Open → Half-open → Closed

Cache Strategies

  • Next.js cache: cacheLife / cacheTag (Next.js 16)
  • Redis: Analytics API caching
  • Client cache: TanStack Query for server state

Related Files

FilePurpose
packages/auth/get-user-auth.tsAuth flow implementation
packages/database/src/schema/Database schema
apps/app/src/lib/notification-queue.tsNotification fanout
apps/api/app/api/webhooks/Webhook handlers