Architecture Overview

OverviewCopy Anchor Link

Danvas is built as a Turborepo monorepo with 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. Public marketing is hosted outside this monorepo (ADR-0081).

System ArchitectureCopy Anchor Link

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]
    App --> Idem[Webhook Idempotency]

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

    Guest[Guest Portal apps/guest] --> GuestDomain[Coupons and Guest NPS]
    GuestDomain --> DB
    GuestDomain --> Identity[Contact Identity]
    App --> GuestDomain
    App --> Identity
    API --> GuestDomain
    GuestDomain --> Notifications

ApplicationsCopy Anchor Link

Key PackagesCopy Anchor Link

Data FlowCopy Anchor Link

Authenticated SessionCopy Anchor Link

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 getActionContext() for authorization guards (with local RBAC and location scoping per ADR-0018)
5. Tenant-owned reads and writes enforce the authorized teamId and, where applicable, locationId; global, reference, audit, migration, and system-owned tables follow their explicit contracts

Background JobsCopy Anchor Link

The API app (apps/api) runs operational jobs via Vercel Cron. The deployed entrypoints and schedules are owned by apps/api/vercel.json; this page intentionally avoids duplicating volatile timing details. Current families include compliance and report reminders, announcement publishing, 7shifts synchronization, coupon expiry, and keep-alive health checks. Certified analytics mart materialization is owned by Dagster, not these API cron handlers.

Coupons, NPS, and customer identityCopy Anchor Link

The operator App owns authorized campaign authoring, immutable publication, issuance recovery, and reports. The Guest portal owns assignment-scoped coupon and survey interactions. Both use shared packages and the database transaction boundary; a public route does not inherit authority from an admin page.

Contact resolution/merge locks precede aggregate association writes. Campaign edit revisions prevent stale publication, and the durable issuance-command fence prevents a lost response from creating another private link. Accepted reservations retain their offer version and absolute server expiry. Reports distinguish guest attestation from verified staff/POS fulfillment; Danvas does not modify Toast checks. Anonymous NPS creates no Contact or contactable recovery case.

Domain events commit with accepted mutations. The shared notification worker reloads authoritative records and delivers through existing queue/Slack ledgers. Provider delivery and cron scheduling do not own coupon capacity or survey completion. See Coupons and Guest NPS for routing, privacy, recovery, and the separate rollout/pilot gates.

Restaurant Analytics Data FlowCopy Anchor Link

Operational analytics (tips, labor, sales, upgrades) are Neon-native. Source and fact tables land in Neon; Dagster owns certified analytics mart materialization, while apps/api cron jobs handle operational orchestration and notifications. Intelligence → Analytics pages read the resulting tables via server actions.

graph LR
    subgraph Danvas["Danvas"]
        APP[apps/app<br/>Intelligence → Analytics]
        API[apps/api<br/>operational crons]
        DAG[Dagster<br/>certified materializations]
    end

    subgraph Neon["Neon PostgreSQL"]
        FCT[public fact tables]
        MART[analytics marts]
    end

    subgraph POS["Toast / 7shifts"]
        TOAST[POS + labor sync]
    end

    TOAST --> FCT
    DAG --> MART
    FCT --> APP
    MART --> APP
    FCT --> API

Key jobs: Dagster daily_certified_metrics_job owns daily/hourly tip and Upgrade partitions; completed_week_metrics_job owns completed-week outputs. Historical replay is an approval-bound Dagster partition repair.

The @repo/telemetry package is product telemetry (PostHog, Vercel Analytics) and is not the tip dashboard read path. See Analytics & Tips Integration.

Tech Stack SummaryCopy Anchor Link

RelatedCopy Anchor Link