How-To Do This

How to build CompanyIQ

Build permission-aware document search and scheduled intelligence that connects knowledge to customers, risks, and opportunities.

CompanyIQ is a company knowledge and opportunity 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

Make company knowledge searchable with source evidence, then combine permitted documents and business records to surface a small number of reviewable risks or opportunities.

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: Reuse the canonical AI source → element → chunk → visual index → embedding pipeline and relate evidence back to canonical business records; do not create a parallel knowledge-table family.

2. Build the working screens

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

• Natural-language knowledge search with citations.
• Source/document detail with processing state.
• Customer 360 with related knowledge and history.
• Scheduled insight queue.
• Evidence review and approved-action workspace.

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

• Apply source, record, field, DataRole, and location access before retrieval.
• Preserve document ownership and effective access when chunking and embedding.
• Require normal action permissions even when AI discovered the opportunity.

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 accepted → extract text and visual evidence → chunk → embed → index.
• Source or permission change → bounded reprocessing and access refresh.
• Scheduled account scan → insight with evidence and expiry.
• Human review → approve, dismiss, or correct insight.
• Approved action → native opportunity/task/workflow with source link.

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

• Accept approved files and source connectors through bounded ingestion.
• Use the current multimodal embedding profile for text, image, and mixed evidence.
• Send approved opportunities into the native CRM/work system, not directly into database tables.

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 secured multimodal retrieval so tables, diagrams, screenshots, and text can all remain evidence. Current vector lanes are 256, 1024, and 1998 dimensions; any manual MRL truncation must be L2-normalized consistently for storage and query.

• Preserve source location and visual evidence during extraction.
• Filter authorized candidates before assembling model context.
• Return evidence links and distinguish contradiction or uncertainty.
• Evaluate retrieval and insight quality against fixed permission-aware fixtures.

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 a small approved document set, answer one cited question, relate evidence to one customer, and run one reviewable opportunity scan that can create a task.

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 text, table, diagram, and screenshot retrieval.
• Prove revoked source access disappears from search and AI context.
• Verify embedding dimensions, normalization, and query/storage parity.
• Trace each insight to source/version and business evidence.

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.