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

Architecture Overview

High-level architecture of the Danvas platform

Overview

Danvas is built as a Turborepo monorepo with three deployable Next.js applications and over 20 shared packages. Each business capability is encapsulated in a reusable @repo/* package, and applications compose these packages to build their user interfaces and APIs.

System Architecture

graph TD
    App[Main Application apps/app] --> UI[UI Design System]
    App --> Auth[Authentication & Security]
    App --> DB[Database & Storage]
    App --> Notifications[Communication & Notifications]
    App --> AI[AI & Analytics]

    API[API Backend apps/api] --> DB
    API --> Auth
    API --> Notifications

    Web[Marketing Website apps/web] --> CMS[CMS & SEO]
    Web --> UI

Applications

Deployment Guide

How Danvas is deployed to production

Data Flow

How data moves through Danvas

On this page

OverviewSystem ArchitectureApplicationsKey PackagesData FlowAuthenticated SessionBackground JobsAnalytics Integration FlowTech Stack SummaryRelated
ApplicationPortPurpose
Main App (apps/app)4000Primary authenticated application — all user-facing features (forms, reports, incidents, admin, chat, schedules)
API Backend (apps/api)4002Headless Next.js app — scheduled cron jobs, webhooks, health checks
Marketing Site (apps/web)4001Public-facing localized, SEO-optimized website

Key Packages

PackagePurpose
@repo/databaseDrizzle ORM + Neon PostgreSQL — schema, migrations, connection pool
@repo/authClerk authentication — user provisioning, role-based access control, session management
@repo/aiVercel AI SDK — chat interface, OpenRouter provider, DeepSeek Chat model
@repo/design-systemUI component library — shadcn/ui primitives, data tables, scheduling UI, Tailwind v4
@repo/slackSlack webhook delivery — DB-backed routing, Block Kit templates, retry logic
@repo/matrixMatrix chat — user provisioning, room management, AI bot
@repo/analyticsPostHog analytics — client + server, Vercel Analytics, Google Analytics
@repo/securityNosecone security headers, AES-256-GCM encryption, bot detection
@repo/rate-limitSliding window rate limiter — Upstash Redis with in-memory fallback
@repo/notificationsWeb Push notification helpers
@repo/emailResend transactional email — React Email templates
@repo/cmsGit-backed MDX content — blog and legal pages
@repo/seoMetadata helpers, sitemap, JSON-LD structured data
@repo/storageVercel Blob — file uploads with HEIC-to-JPEG conversion
@repo/feature-flagsPostHog feature flags + Vercel Toolbar
@repo/observabilitySentry error tracking + BetterStack logging

Data Flow

Authenticated Session

  1. User signs in via Clerk at (unauthenticated)/sign-in
  2. @repo/auth/server provisions the user in the database (or links them to a pending invite)
  3. The authenticated layout wraps all pages with SidebarProvider + NotificationsProvider
  4. Server Actions and API routes use requireUserAuth() / requireAdmin() for guard checks
  5. All queries filter by teamId (Clerk org) for multi-tenant isolation

Background Jobs

The API app (apps/api) runs scheduled cron jobs via Vercel Cron:

  • Compliance nudges — every 15 min during ops hours, checks for unfiled reports and sends Slack reminders
  • Report reminders — nightly at 8PM UTC, summarizes missing staff and manager reports
  • Hero aggregation — weekly MVP calculation from shift report hero mentions
  • Keep-alive — daily database ping to prevent connection drops

Analytics Integration Flow

The @repo/analytics package connects to an external analytics service that aggregates data from Toast POS and other external systems:

graph LR
    subgraph Danvas["Danvas"]
        APP[apps/app]
        ANACLIENT[@repo/analytics<br/>Client Library]
    end

    subgraph External["External Services"]
        ANALYTICS_API[Analytics API<br/>ANALYTICS_API_URL]
        TOAST[Toast POS API]
        REDIS[(Redis Cache)]
        PG[(PostgreSQL)]
    end

    APP --> ANACLIENT
    ANACLIENT --> ANALYTICS_API
    ANALYTICS_API --> TOAST
    ANALYTICS_API --> REDIS
    ANALYTICS_API --> PG

This client-server architecture ensures:

  • Isolation: Danvas never calls Toast directly
  • Caching: Redis layer reduces API load
  • Reliability: Circuit breaker pattern (5 failures → 60s timeout)
  • Consistency: Zod schemas validate all responses

Tech Stack Summary

LayerTechnology
FrameworkNext.js 16 (App Router)
MonorepoTurborepo v2 + Bun
DatabaseNeon PostgreSQL + Drizzle ORM
AuthClerk (multi-tenant via orgs)
AIOpenRouter → DeepSeek Chat
UIshadcn/ui + Tailwind v4
StateTanStack Query + Zustand + nuqs
EmailResend + React Email
StorageVercel Blob
AnalyticsPostHog + Vercel Analytics + Google Analytics
MonitoringSentry + BetterStack
PushWeb Push API + Matrix + Slack
DeployVercel

Related

Database & Schema

Authentication & Auth

Monorepo Packages