How-To Do This

How to build CustomerPortal

Build a branded customer workspace that shares selected requests, files, messages, approvals, and milestones while protecting internal work.

CustomerPortal is a customer collaboration portal 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 customers a simple, branded place to collaborate on their own work while internal teams keep private fields, notes, assignments, AI guidance, and operating detail in the same governed application.

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: Derive customer membership server-side and explicitly mark shareable content; never trust a customer-supplied account or request identifier as authorization proof.

2. Build the working screens

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

• Branded customer home with their requests and milestones.
• New-request and document-upload forms.
• Shared request timeline with messages and files.
• Customer approval workspace.
• Internal sidecar with private notes, assignment, workflows, and AI guidance.

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

• Create a customer user type using existing authorization—not a new authentication system.
• Require verified membership in the request's customer account.
• Enforce shared/private visibility server-side for fields, comments, files, and events.

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

• Invitation → verified membership → portal access.
• Customer request → validation → internal queue and SLA.
• Internal status update → deliberately published customer update.
• File upload → scan/validation → shared or internal review state.
• Customer approval → immutable decision evidence → next internal action.

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 the same login/session APIs and custom domain/branding capabilities.
• Connect notifications and approved scheduling, billing, storage, or support systems.
• Keep storage/provider tokens and internal identifiers out of portal output.

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 internal summarization, routing, and prepared responses over permitted context. Expose AI output to customers only through an explicitly designed and tested customer-visible experience.

• Separate internal-only and customer-visible context before retrieval.
• Prepare replies or status summaries as reviewable suggestions.
• Never allow private notes or inaccessible files into customer output.
• Record the approved content version that was published.

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: Invite one customer member, let them submit a request and file, route it internally, publish one status update, and capture one customer approval.

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 cross-customer identifier substitution on every route.
• Test private fields, comments, files, counts, and search results for leakage.
• Test revoked membership and expired invitation behavior.
• Trace every externally visible update to its author/approval.

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.