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]
    end

    subgraph Backend["Backend Packages"]
        AUTH[@repo/auth<br/>User provisioning<br/>Access control]
        DB[@repo/database<br/>Drizzle ORM<br/>PostgreSQL]
        ANALYTICS[@repo/telemetry<br/>PostHog client<br/>External API]
        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]
        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 --> SLACK
    SLACK --> SLACK_API

    APP --> NOTIF
    NOTIF --> PUSH

    APP --> POSTHOG

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

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

    User->>Action: Submit form
    Action->>Auth: getActionContext("admin")
    Auth-->>Action: { auth: { userId, teamId, role, locationIds } } (or redirect /403)
    Action->>DB: Begin transaction
    Action->>DB: Write data
    Action->>Audit: logAudit() (same tx)
    Action->>DB: Commit
    Action->>Slack: Send notification
    Action-->>User: Success response

sequenceDiagram
    participant Service
    participant API
    participant Webhook
    participant Idem
    participant Auth
    participant DB

    Service->>API: POST /webhooks/clerk (svix headers)
    API->>Idem: claimIdempotencyKey({ source, eventType, key })
    Idem-->>API: true (first time) | false (duplicate)
    alt first delivery
        API->>Webhook: verify() signature
        API->>Auth: provisionUser()
        Auth->>DB: Create/update user
    else duplicate
        API-->>Service: 200 (already processed)
    end
    API-->>Service: { received: true }

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