Unified inbox (work items)
Contributor and operator reference. For the full product vision, phased rollout, and edge-case decisions, read The inbox is the product.
What it is
Section titled “What it is”The unified inbox is a work queue backed by the workItems table. Email- and upload-sourced orders appear as rows; users review in full-page flows, with optional team dashboard metrics, snooze, and keyboard-driven navigation. When the legacy path is off, the app reads work items instead of scanning emailEvents metadata alone.
Feature flags
Section titled “Feature flags”| Flag | Role |
|---|---|
unified_inbox_v2 | Org-scoped Flagsmith flag toggling work-item UI, redirects, and APIs that assume work items. |
email_enabled | Shows inbox / email-based entry points (used together in staging setups). |
Script to enable both in a Flagsmith environment: infrastructure/flagsmith/scripts/enable_unified_inbox_for_env.py. Flag definitions ship in infrastructure/flagsmith/configs/flags.json. Local fallback defaults live in apps/webapp/src/middleware/feature-flags.ts.
Data layer
Section titled “Data layer”- Schema:
packages/db/src/schema/work-items.ts - Dual-write: Work items are created in the same transactional paths as inbound email (
/api/webhook/inbound-email) and PDF upload handlers so legacy and v2 stay consistent during rollout.
Webapp (Astro + React)
Section titled “Webapp (Astro + React)”- Inbox page:
apps/webapp/src/pages/inbox.astro - UI:
apps/webapp/src/components/inbox/* - Queries / helpers:
apps/webapp/src/lib/inbox/* - Review URLs:
apps/webapp/src/lib/inbox/work-item-review-url.ts,inbox-return-to.ts - Representative APIs:
apps/webapp/src/pages/api/work-items/*(dashboard, bulk actions, snooze, check-updates, test order, admin backfill trigger) - Temporal client helpers:
apps/webapp/src/lib/temporal.ts(startWorkItemBackfillWorkflow, PDF extraction unchanged onpdf-extractionqueue)
Temporal (TypeScript worker)
Section titled “Temporal (TypeScript worker)”Package: apps/ts-temporal-worker
Task queue: erp-unlocked-ts
| Workflow | Purpose |
|---|---|
WorkItemBackfillWorkflow | Migrate existing email events into workItems (idempotent; fixed workflow id work-item-backfill). |
WorkItemUnsnoozeWorkflow | Periodic unsnooze of rows past snoozedUntil (intended as a schedule; see workflow file for CLI hints). |
Requires TEMPORAL_ADDRESS (and related TLS vars) where the webapp starts backfill or PDF workflows.
Related
Section titled “Related”- Deferred product work:
debt/backlog/projects/unified-inbox/TODOS.md - Email pipeline (high level):
docs/designs/inbox-is-the-product.md(diagrams and dual-write notes) - User operations guide:
docs/product/inbox-rbac-sla-operations-guide.md(RBAC capabilities, SLA policy controls, supervisor/admin dashboard actions)