How-To Do This

How to build TeamBox

Build a shared communications command center with channel normalization, AI triage, ownership, suggestions, and governed execution.

TeamBox is a universal team and ai inbox pattern. This guide turns the product concept into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Define the outcome before the screens

Give a team one attention queue for incoming communications while preserving the native conversation, business record, ownership history, and approval boundary behind each item.

1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

Relationship rule: Universal Inbox points to conversations, forms, and business records; it does not replace them as the source of truth.

2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

• Shared inbox with queue, owner, priority, SLA, and channel filters.
• Conversation workspace with related customer/project context.
• Triage and reassignment panel.
• Suggested reply/action approval panel.
• Queue performance and handoff review.

Use Puck for the normal visual experience. Keep stable block identity when using Monaco advanced JSON mode so future template upgrades can merge safely.

3. Set access before adding automation

• Scope queues by role, DataRole, team, and location.
• Apply the related record's permission checks before showing context.
• Separate assignment, response, approval, and high-impact action capabilities.

User Type menus establish eligible page routes for each audience. They do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

4. Add the core workflows

• Channel event → native conversation/message → inbox activity.
• Activity version → classify → route by deterministic rules plus permitted AI output.
• Assignee response or suggestion → approval policy → send/action.
• New message or source change → increment activity version and stale old preparation.
• SLA threshold → escalation and visible ownership event.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

5. Connect channels and outside systems

• Connect email, SMS, forms, and authenticated inbound events.
• Normalize provider delivery callbacks into native message state.
• Use action-specific connectors for calendar, CRM, task, or external updates.

Use managed connections, OAuth connectors, inbound endpoints, and webhooks. Put specialized SDKs or private processing behind a declared appliance endpoint; never expose provider credentials to a page.

6. Add AI as a governed layer

Use AI for triage, summaries, and prepared actions over permission-filtered context. Preserve the activity-version stale-context fence from preparation through execution.

• Classify intent/urgency with confidence and model version.
• Attach related-record evidence before suggesting work.
• Prepare structured replies and actions separately.
• Refuse or re-prepare when the activity version changes.

AI and retrieval must apply CanAiReadRecords, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

7. Ship one complete vertical slice

Recommended first release: Receive one form or email, create the native conversation and inbox activity, classify and assign it, then let the assignee approve and send one prepared reply.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

8. Validate, package, and operate

• Test duplicate and out-of-order provider events.
• Prove queue and related-record permissions both apply.
• Prove stale suggestions cannot send or mutate.
• Trace channel receipt through assignment, approval, and delivery.

Publish a reviewed exact version as a template when the pattern is reusable. If you sell it, complete the marketplace preparation checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

Built-in data path: React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.