How-To Do This

How to build ActiveWorkplace

Build a Wave-like shared coordination surface around any permitted Record and its secured recursive relationship graph.

ActiveWorkplace is a recursive work coordination 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

Let a team pin an existing business Record, see the permitted connected work around it, assign explicit responsibilities, notice inactivity, and replay retained history without copying the underlying business data or creating a second permission system.

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: Keep every business item in its native module. Reuse typed Record Relations for the Active Graph and store only bounded identities/topology in workplace snapshots.

2. Build the working screens

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

• My/All ActiveWorkplaces list with search and Pulse filters.
• Pin-record picker over currently visible Records.
• Workplace detail with root, Pulse, graph, participants, and activity.
• Participant/responsibility editor for eligible Users, GoClaws, and Workflows.
• Read-only Graph Playback with a clear historical banner and Return to current action.

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

• Require current read/edit permission to pin and manage the root.
• Reauthorize every graph node by tenant, SaaS app, DataRole, and location before display.
• Require independent AI-read access for a GoClaw backing user; assignment never grants it.
• Intersect playback identities with current authorization and remove all historical mutation paths.

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

• Visible Record -> pin once -> initial graph snapshot and owner participant.
• Meaningful update or related Record change -> refresh activity/Pulse and retained state.
• Waiting expiry or inactivity -> Active/At Risk/Stale transition -> create or touch Inbox attention.
• Eligible participant assignment -> responsibility recorded without changing its authority.
• Resolved -> retain history and prevent accidental active duplicate behavior according to policy.

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

• Use Universal Inbox for human attention rather than creating a separate alert queue.
• Use existing GoClaw events/suggestions/actions for AI participation and material approval.
• Use normal workflow definitions and APIs for deterministic business actions.
• Keep ActiveWorkplace tenant-local; involve AI Orchestration only when an AI job actually runs.

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

AI is optional. A GoClaw can monitor, research, summarize, and prepare work only through its represented user's current AI-read envelope. Record Pulse itself is deterministic and does not need a model.

• Start with a non-acting GoClaw watcher and a clear responsibility.
• Retrieve only currently authorized graph records and fields.
• Represent any material next step as the existing governed suggestion/action contract.
• Keep human approval for customer-facing or material work until policy and harness evidence support more authority.

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: Pin one case or opportunity, show a cyclic three-record graph, add one person and one read-only GoClaw, let inactivity create one Inbox item, and replay the workplace with every write control removed.

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

• Prove a hidden-location graph branch and its edges are omitted.
• Prove a GoClaw without independent CanAiReadRecords cannot be assigned.
• Evaluate Pulse twice and prove the second run does not duplicate Inbox attention.
• Change current location access and prove playback cannot restore the old view.
• Retry pinning and prove the same active root workplace is returned.

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.