How-To Do This

How to build Northstar

Build evidence-backed executive metrics, material-change signals, forecasts, scenarios, and replayable briefings.

Northstar is a executive business intelligence 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

Compress operating changes into a small number of material signals and decisions, while letting leaders inspect the source, assumptions, owner, and confidence behind every claim.

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: Every displayed number and narrative claim must resolve to versioned definitions, observations, source watermarks, and the briefing snapshot that used them.

2. Build the working screens

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

• Executive scorecard with freshness and quality indicators.
• Material-change queue.
• Metric drill-down with source and forecast history.
• Scenario comparison workspace.
• Briefing editor, snapshot, and decision log.

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

• Separate broad aggregate visibility from sensitive underlying records.
• Restrict finance, people, customer, and departmental detail with existing permissions.
• Keep financial commitments and operating mutations behind action-specific approval.

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

• Source update → validate freshness/quality → compute observation.
• Threshold/materiality rule → signal with owner and evidence.
• Scheduled synthesis → draft briefing.
• Briefing review → freeze evidence manifest and assumptions.
• Decision → assign follow-up work; never rewrite the historical briefing.

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

• Ingest approved finance, CRM, support, product, and custom operational aggregates.
• Use bounded read APIs or scheduled imports with watermarks.
• Send approved follow-ups to the native work system while retaining a decision link.

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 to synthesize permitted evidence and explain changes, not to invent metrics or silently alter forecasts. Definitions, calculations, materiality rules, and source freshness remain explicit.

• Retrieve only evidence visible to the current reader.
• Require citations to metric observations and source records.
• Show uncertainty, stale inputs, and conflicting evidence.
• Freeze the exact evidence and prompt/harness version used in a briefing.

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: Ingest three KPIs, detect one threshold crossing, draft an evidence-linked weekly briefing, and freeze the reviewed briefing with one assigned decision.

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

• Recompute known metric fixtures deterministically.
• Test stale, missing, and conflicting source data.
• Prove restricted readers cannot drill into protected evidence.
• Reconstruct a briefing from its frozen evidence manifest.

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.