How-To Do This

How to build OpsAtlas

Build an owned, revisioned operating-memory product with permission-aware answers, evidence, review work, knowledge gaps, and governed actions.

OpsAtlas is a ai operational knowledge core 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

Turn a small set of approved operating procedures into maintained Knowledge Core records that employees and agents can search in context, verify against exact revisions, and use to start the right governed workflow.

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: Relate each procedure to the products, departments, locations, assets, cases, work orders, conversations, files, and workflows it governs; a relation improves context but never grants access.

2. Build the working screens

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

• Knowledge home with collections, search, freshness, and health.
• Item editor/view with ownership, revisions, publication, relations, and citations.
• Review queue connected to Tasks and Universal Inbox.
• Question, feedback, and knowledge-gap workspace.
• Employee/agent answer surface with source and freshness evidence.

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 read, edit, publish, manage ownership/reviews, link, ask/answer, and support-learning capabilities.
• Apply tenant, DataRole, location, record, field, and CanAiReadRecords checks before retrieval or model context.
• Keep customer-safe and internal-only collections distinct and recheck disclosure at response time.

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

• Draft → review/edit → permission-checked publish → immutable revision citation.
• Review due → Task/Inbox attention → confirm current, revise/republish, reassign, or archive.
• No authoritative answer → Knowledge Question → assignment/answer → optional GeneratedCandidate Draft.
• Usage/negative feedback/repeated gaps → secured health signal and owner follow-up.
• Resolved support case → structured sanitization → owner/review Task → Draft candidate; authorized publication only.

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 only approved current sources with explicit audience, owner, authority, review policy, and AI eligibility.
• Preserve files, PDF pages, images, tables, diagrams, and screenshots through the canonical multimodal AI pipeline.
• Expose read-only diagnostics separately from knowledge; route any material action through existing workflow/GoClaw approval contracts.

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 Knowledge Core as the governed source layer for secured semantic and multimodal retrieval. Only Published, AI-eligible revisions enter normal RAG, and every answer retains exact source/revision/freshness evidence.

• Index approved revisions through the existing source, element, chunk, visual-index, and embedding chain.
• Filter by the represented user's full security envelope before context assembly.
• Prefer current Official/Verified evidence and surface conflicts, staleness, or missing authority.
• Create a question or escalation instead of fabricating an unsupported answer.

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: Create one customer-safe collection with an owner and 30-day review policy, publish three approved procedures, relate one to a business record, answer one question with an exact citation, and turn one missing answer into a reviewable Knowledge Question.

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 Draft, archived, stale-policy, internal-only, other-tenant, other-location, and AI-denied material cannot enter a normal answer.
• Prove citations resolve to the exact immutable revision and source evidence.
• Prove duplicate review cycles/questions/support candidates remain idempotent.
• Change source activity or permissions and verify stale context or revoked access fails closed.

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.