SoConnective — Documentation

Date: 2026-06-13 Status: Accepted — AI Operator live & verified; rest staged in this ADR

Context

Feedback OS is AI-native. Two distinct AI surfaces are required, and they must not be conflated. Separately, account setup must be consistent whether done by a human or by the AI — there must be a single source of truth for "what a business of type X needs".

Decision

Two distinct AIs

1. AI Operator (platform-level, built-in). One assistant for the whole platform, powered by the platform's own Anthropic key (ANTHROPIC_API_KEY env), available in every account. It is not a chatbot and never discusses anything outside the product. Its job is to onboard, configure and guide inside the currently-active account: set up the CRM, install the right marketplace modules for the business, connect channels/platforms, explain where to find things, and produce reports/trends from the account's own data. It acts through tools that are tenant- and permission-scoped (pCreate/pUpdate enforce isolation). Model: claude-opus-4-8. Lives at /dashboard/assistant. Live & verified (creates real records in the correct tenant via tool use).

Roadmap for the Operator (approved): proactive setup checklist (reads account state, suggests next step); real configuration tools (install_module, connect_channel, create_pipeline, create_template, create_automation); deep-link guidance (clickable links to the right section); one-click vertical starter-pack install (below).

2. Inbox AI (marketplace module, per-account). A separate, installable marketplace module that each account configures with its own provider key (BYOK, stored in the tenant-scoped integrations collection). It lives in the Inbox, is not a live chat — its only job is to draft/assist message content with full awareness of the contact it is talking to. It loads the contact's 360° context (contact + company + open deals + activities + lifecycle

the full conversation) and the account's brand voice/persona (agents collection), then: drafts replies, suggests next best action, summarizes the thread, detects intent/sentiment, and extracts tasks/deals from the conversation. Extremely capable, always directed at the contact and its relationships. Cost controlled via prompt caching of the stable prefix and per-account token metering.

Marketplace: modules and starter packs

Module — an installable capability unit (e.g. Inbox AI, a channel connector, a reporting pack). Platform-level catalog; enabled per account.
Starter pack — a curated collection of modules + config for a business vertical (aesthetic clinic, marketing agency, e-commerce, …). A starter pack is not a module; it is a bundle. It lives in the marketplace and can be installed manually with one click.
Single source of truth. The AI Operator installs accounts using the same starter-pack definitions as manual install — so the AI "always follows the pattern". One definition, two entry points (human click / AI tool).

starter_pack (vertical)
  ├── modules: [moduleKey, …]        ← installed into the account
  ├── pipeline: { name, stages[] }   ← CRM scaffold
  ├── templates: [ … ]               ← message templates
  └── config: { … }                  ← sensible defaults
manual install ─┐
AI Operator ────┴──▶ applyStarterPack(pack, account)  // one code path

Data model (to build)

modules (platform catalog): key, name, description, category, icon, status.
starter-packs (platform catalog): key, name, vertical, modules[], pipeline, templates[], config.
per-account install state on tenants.entitlements (or a join collection): { modules: string[], packs: string[] }.

Cross-cutting (approved)

Audit every AI action to the audit log (who/what/when, undoable).
Token metering + monthly caps per account, surfaced in System Health.
Prompt caching of the stable persona/context prefix for the Inbox AI.

Consequences

The AI Operator and manual setup can never drift — same starter-pack code path.
Inbox AI usage is paid per-agency (BYOK) and metered; the Operator is a platform cost (platform key) — clear cost model at scale.
New verticals = new starter-pack definitions; no code churn.