{"slug":"architecture/PLATFORM_ACTIVATION_FRAMEWORK","title":"Platform Activation Framework","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/PLATFORM_ACTIVATION_FRAMEWORK.mdx","bytes":18680,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n**The Frozen Architecture: Proving IntegrateWise is a Platform**\n\n---\n\n## The Acceptance Test\n\n> **Swap any frontend without changing business logic.**\n>\n> Replace Lovable ↔ v0 ↔ Replit ↔ Electron ↔ Next.js on top of the same tenant, same data, same capability set — and the user behavior must be identical.\n\nIf this passes, **platform-first is proven.**\n\n---\n\n## Why This Matters\n\n**Old thinking:** \"Build beautiful UI in this tool, then rebuild it in that tool\"\n**Platform thinking:** \"Build ONE SDK. Every tool becomes a Projection.\"\n\nThe breakthrough: **The product is not the UI. The product is the Capability APIs + SDK.**\n\n---\n\n## The Eight Frozen Contracts\n\nThese are the load-bearing API of IntegrateWise. No frontend invents payloads. Every interaction flows through these envelopes.\n\n### 1. PlatformRequest — Every request enters through this\n\n```typescript\ninterface PlatformRequest<TKind extends PlatformOp, TPayload> {\n  id:        string             // request id (idempotency key)\n  op:        TKind              // discriminated union: \"read\" | \"write\" | \"execute\" | \"search\"\n  payload:   TPayload           // op-specific body\n  actor:     ActorRef           // who: human | twin | service\n  tenant:    TenantId           // tenant boundary (security)\n  context:   ContextRef         // workbench projection + current capability\n  trace:     TraceMeta          // audit + replay trail\n}\n```\n\n### 2. PlatformResponse — Every response leaves through this\n\n```typescript\ninterface PlatformResponse<TResult, TError = PlatformError> {\n  requestId: string             // matches PlatformRequest.id\n  status:    \"ok\" | \"partial\" | \"denied\" | \"error\"\n  result?:   TResult\n  error?:    TError\n  cursor?:   string             // pagination / continuation token\n  audit?:    AuditRef           // link into Memory audit boundary\n  replay?:   ReplayHandle       // how to replay this operation\n}\n```\n\n### 3. Capability — The atomic unit of work\n\n```typescript\ninterface Capability {\n  id:          CapabilityId     // stable id: \"renewal-risk\" | \"account-health\"\n  version:     SemVer           // \"1.4.0\" (major=breaking, minor=additive)\n  projection:  Projection[]     // how it surfaces in Workbench lenses\n  inputs:      SchemaRef        // input contract (JSON Schema)\n  outputs:     SchemaRef        // output contract\n  actions:     ActionRef[]      // side-effecting verbs: create | update | delete | execute\n  providers:   ProviderRef[]    // external systems it can touch\n  governance:  GovernancePolicy // approval rules + audit + scope\n}\n```\n\n### 4. Entity — The thing a Capability operates on\n\n```typescript\ninterface Entity {\n  id:        EntityId\n  type:      EntityType         // Account | Contact | Deal | Invoice | Task\n  tenant:    TenantId\n  fields:    Record<string, unknown>\n  memory:    MemoryRef          // link to human/twin/org/audit memory\n  capabilities: CapabilityRef[] // what this entity can do\n}\n```\n\n### 5. Memory — The knowledge triple with boundaries\n\n```typescript\ninterface Memory {\n  scope:     \"human\" | \"twin\" | \"org\" | \"audit\"  // CRITICAL boundary\n  entity:    EntityRef\n  content:   unknown            // arbitrary JSON\n  citations: EntityRef[]        // what this memory references\n  ttl:       number             // seconds to live (resets on access)\n  redaction: RedactionRule[]    // what to hide from whom\n}\n```\n\n### 6. Proposal — Decision / change lifecycle\n\n```typescript\ninterface Proposal {\n  id:        ProposalId\n  capability: CapabilityRef\n  rationale: string\n  proposedBy: ActorRef          // twin OR human\n  approvals:  ApprovalRef[]     // governance gates (who must sign off)\n  status:    \"draft\" | \"pending\" | \"approved\" | \"denied\" | \"executed\"\n}\n```\n\n### 7. Approval — The approval grain\n\n```typescript\ninterface Approval {\n  id:       ApprovalId\n  proposal: ProposalRef\n  actor:    ActorRef            // who is deciding\n  decision: \"approve\" | \"deny\" | \"request-info\"\n  reason?:  string\n  at:       ISODateTime\n}\n```\n\n### 8. Projection — How Capabilities are rendered per lens\n\n```typescript\ninterface Projection {\n  lens:      WorkbenchLens      // Sales | CS | Finance | Marketing | Operations | HR | Executive | Personal\n  view:      ViewSpec           // what fields to show, how to arrange, what actions available\n  capability: CapabilityRef     // which capability this projection is rendering\n}\n```\n\n---\n\n## The SDK Surface (`@integratewise/sdk`)\n\nEvery method in the SDK compiles to one `PlatformRequest` envelope and unwraps one `PlatformResponse`. From any framework.\n\n### Entity Discovery\n\n```typescript\niw.accounts.list(filters?: AccountFilter):        Promise<PlatformResponse<Entity[]>>\niw.accounts.get(id: EntityId):                    Promise<PlatformResponse<Entity>>\niw.contacts.list(filters?: ContactFilter):        Promise<PlatformResponse<Entity[]>>\niw.contacts.get(id: EntityId):                    Promise<PlatformResponse<Entity>>\niw.entity360(id: EntityRef):                      Promise<PlatformResponse<EntityBundle>>\n```\n\n### Capability Discovery & Execution\n\n```typescript\niw.capabilities.list():                           Promise<PlatformResponse<Capability[]>>\niw.capabilities.describe(id: CapabilityId):       Promise<PlatformResponse<Capability>>\niw.capability(id: CapabilityId, args):            Promise<PlatformResponse<CapabilityOutput>>\n\n// Examples:\niw.capability(\"renewal-risk\", { account: \"acme-123\" })\niw.capability(\"account-health\", { account: \"acme-123\" })\niw.capability(\"ar-exposure\", { filters: { overdue: true } })\n```\n\n### Memory & Knowledge\n\n```typescript\niw.memory.write(scope: MemoryScope, content):     Promise<PlatformResponse<MemoryRef>>\niw.memory.read(ref: MemoryRef):                   Promise<PlatformResponse<Memory>>\niw.memory.search(query, scope?, topK?):           Promise<PlatformResponse<SearchHit[]>>\niw.knowledge.search(q):                           Promise<PlatformResponse<KnowledgeHit[]>>\n```\n\n### Proposals & Approvals\n\n```typescript\niw.proposals.list(filters?):                      Promise<PlatformResponse<Proposal[]>>\niw.proposals.create(capability, args, rationale): Promise<PlatformResponse<Proposal>>\niw.proposals.approve(id, reason?):                Promise<PlatformResponse<Approval>>\niw.proposals.deny(id, reason):                    Promise<PlatformResponse<Approval>>\niw.proposals.execute(id):                         Promise<PlatformResponse<ExecutionReceipt>>\niw.governance.policy(capabilityId):               Promise<PlatformResponse<GovernancePolicy>>\n```\n\n### Providers & Tools\n\n```typescript\niw.tool(id: ToolRef, args):                       Promise<PlatformResponse<ToolReceipt>>\niw.provider(id: ProviderRef, args, idempotencyKey?): Promise<PlatformResponse<ProviderReceipt>>\niw.workflow.start(workflowRef, args):             Promise<PlatformResponse<WorkflowHandle>>\niw.workflow.status(handle):                       Promise<PlatformResponse<WorkflowState>>\n```\n\n### Signals & Notifications\n\n```typescript\niw.notifications.subscribe(topic, handler):       UnsubscribeFn\niw.notifications.publish(topic, payload):         Promise<void>\niw.signals.observe(pattern):                      AsyncIterable<Signal>\n```\n\n### Strategy & Analytics\n\n```typescript\niw.strategy.summary(period):                      Promise<PlatformResponse<ExecSummary>>\niw.workbench.lens(lens: WorkbenchLens):           Promise<PlatformResponse<ProjectionSpec>>\niw.analytics.run(query: AnalyticsQuery):          Promise<PlatformResponse<AnalyticsResult>>\n```\n\n---\n\n## How a Frontend Connects (Three Lines)\n\n```typescript\n\nconst iw = new IntegrateWise({\n  tenant:   process.env.IW_TENANT!,\n  identity: process.env.IW_IDENTITY!,    // OAuth or service token\n  runtime:  \"browser\" | \"electron\" | \"server\" | \"mobile\"\n});\n\n// Now use it from any framework\nconst health = await iw.accounts.health(accountId);\nif (health.result?.atRisk) {\n  const proposal = await iw.proposals.create(\n    \"renewal-risk\",\n    { account: accountId },\n    \"Detected deteriorating engagement\"\n  );\n}\n```\n\n---\n\n## Layering: Frontend → Platform\n\n```\n┌─────────────────────────────────────────────┐\n│  UI Surface Layer                           │\n│  React · Lovable · v0 · Replit · Electron  │\n│  Next.js · React Native                     │\n└─────────────────────────────────────────────┘\n                    ↓\n┌─────────────────────────────────────────────┐\n│  Projection Layer                           │\n│  (Lens Adapter)                             │\n│  Sales → CS → Finance → Ops → Exec → ...    │\n└─────────────────────────────────────────────┘\n                    ↓\n┌─────────────────────────────────────────────┐\n│  Capability SDK (@integratewise/sdk)        │\n│  iw.accounts | iw.capability | iw.memory    │\n│  iw.proposals | iw.provider | iw.workflows  │\n└─────────────────────────────────────────────┘\n                    ↓\n═══════════════════════════════════════════════════════════════════\n            INTEGRATEWISE PLATFORM (Frozen Contracts)\n═══════════════════════════════════════════════════════════════════\n┌─────────────────────────────────────────────┐\n│  PlatformRequest / PlatformResponse         │\n│  (Load-bearing envelopes)                   │\n└─────────────────────────────────────────────┘\n                    ↓\n┌─────────────────────────────────────────────┐\n│  Capability APIs                            │\n│  (Capability-first, not endpoint-first)     │\n│  /capabilities/:id (canonical)              │\n│  /entities/:id                              │\n│  /memory/:id                                │\n│  /proposals/:id                             │\n└─────────────────────────────────────────────┘\n                    ↓\n┌─────────────────────────────────────────────┐\n│  Adaptive Spine                             │\n│  (Kernel → Worker → Capability Engine)      │\n│                                             │\n│  Services:                                  │\n│  • Identity (Auth, Users, Teams, Roles)     │\n│  • Capability Registry                      │\n│  • Entity360                                │\n│  • Memory (Scopes: human/twin/org/audit)   │\n│  • Knowledge                                │\n│  • Governance + Approval                    │\n│  • Workflow + Kernel                        │\n│  • Signals                                  │\n│  • Provider + Connector                     │\n│  • Notification                             │\n│  • Twin (Participant, not product)          │\n└─────────────────────────────────────────────┘\n                    ↓\n┌─────────────────────────────────────────────┐\n│  Connected Applications (100+)              │\n│  Gmail · Slack · GitHub · HubSpot · Figma   │\n│  Notion · Salesforce · Drive · Linear · ... │\n└─────────────────────────────────────────────┘\n```\n\n---\n\n## Decision Rules\n\n1. **No new endpoint unless it is a capability.** `/accounts` is forbidden. `/capabilities/account-health` is canonical.\n2. **Every Capability has a governance field** before it ships.\n3. **Every Provider call takes an idempotency key.** Replay is mandatory.\n4. **Every Capability has a version.** Major bumps are breaking; minors are projection-only.\n5. **The SDK is the public API.** Endpoints can be deprecated; the SDK cannot without a Major version.\n6. **No business logic in frontends.** If logic bleeds into UI, file an issue against the Capability, not the frontend.\n\n---\n\n## The Eight Workbench Lenses\n\nEvery Capability is rendered through one or more of these projections:\n\n| Lens | Focus | Metrics | Capabilities |\n|------|-------|---------|--------------|\n| **Sales** | Pipeline, quota, close | ARR, pipeline value, win rate | renewal-risk, account-health, qbr-brief |\n| **CS** | Health, risk, expansion | NPS, health score, churn risk | account-health, renewal-risk, expansion-opp |\n| **Finance** | AR, AP, forecast | DSO, cash flow, forecast accuracy | ar-exposure, ap-aging, forecast |\n| **Marketing** | Campaigns, funnel, pipeline | CAC, conversion, MQL-to-SQL | lead-scoring, campaign-roi, segment |\n| **Operations** | Flow, supply, SLA | SLA compliance, cycle time, throughput | workflow-status, sla-breach, capacity |\n| **HR** | People, ops, review | headcount, retention, engagement | performance-review, hiring, succession |\n| **Executive** | Strategy, KPIs, risk | revenue, margins, risk score | strategy-summary, kpi-dashboard, risk-register |\n| **Personal** | Life, goals, lifeOS | energy, progress, impact | goal-tracking, note-search, reflection |\n\n---\n\n## Platform Activation Roadmap\n\n### Phase 0 — Stabilize (Jan 21 → Feb 7)\n- ✓ Continuity Bridge Vercel build\n- ✓ Identity / Tenant onboarding\n- ✓ Vercel UI integration sanity check\n\n### Phase A — Backend Completion (6 weeks)\nComplete all services behind Capability contracts:\n- Capability Registry (v1.0 + versioning)\n- Entity360 (joins memory + signals + capabilities)\n- Memory (scopes: human/twin/org/audit + TTL + redaction)\n- Knowledge (ingestion + retrieval)\n- Signals (NEW service — observe + replay)\n- Strategic Hub (Capability + Exec projection)\n- Governance + Approval (policy on every Capability)\n- Workflow (Kernel schedules ACTIONS)\n- Notification (Provider action variant)\n- Search (Memory + Entity360 + Knowledge)\n- Analytics (Capability projection)\n- Connector (Continuity sync spine)\n- Provider (idempotency keys mandatory)\n- Runtime (projection dimension)\n\n### Phase B — Freeze Platform Contracts (2 weeks, blocked on Phase A 80%)\n- ✓ PlatformRequest / Response envelopes (frozen)\n- ✓ Capability contract (typed)\n- ✓ Entity, Memory scopes, Proposal / Approval\n- ✓ ToolAction / ProviderAction / Search / Projection\n- ✓ governance field mandatory on every Capability\n- Versioning rules\n\n### Phase C — Capability APIs + SDK (3 weeks, blocked on Phase B)\n- ✓ Publish Capability APIs (no /accounts endpoints)\n- ✓ Publish @integratewise/sdk (TS first; Python + Go follow)\n- ✓ Reference SDK tests against Capability spec\n- ✓ Idempotency documented on every Provider call\n\n### Phase D — Frontend Swap Validation (acceptance test)\n1. Pick one Capability: `renewal-risk`\n2. Build the same screen 3 ways: Lovable, Replit, v0\n3. Each consumes `@integratewise/sdk` against same tenant\n4. Diff outputs — must be byte-identical\n5. Repeat for: `account-health`, `memory.search`, `strategy.summary`\n6. **Acceptance:** business logic untouched across 3 builds\n\n### Phase E — Re-platform existing L1/L2 surfaces\n- Vercel UI → Projection adapter → SDK calls only\n- v0 prototypes → SDK\n- Lovable apps → SDK\n- Replit apps → SDK\n- Electron → SDK\n\n---\n\n## Success Criteria: Platform Activation Complete\n\nWhen you can answer YES to all five:\n\n1. ☑ Phase A services are at v1.0, all behind Capability contracts\n2. ☑ Platform contracts are frozen, versioned, and published as spec\n3. ☑ `@integratewise/sdk` ships, and a Capability looks identical from Lovable, v0, Replit, Electron, Vercel UI\n4. ☑ Same tenant + same Capability ⇒ swapping UI surface produces byte-identical outputs\n5. ☑ A new Workbench lens is built in days by composing Capability APIs — no new backend code\n\n---\n\n## What This Means\n\n**Before Platform Activation:**\n- Each frontend is a full-stack application\n- Business logic spread across multiple tools\n- Adding a new UI tool = rebuilding everything\n\n**After Platform Activation:**\n- Each frontend is a **Projection** of the same Spine\n- Business logic lives in **Capabilities**\n- Adding a new UI tool = adding a Projection adapter (days, not weeks)\n\n**The moat:** Once frozen, the Platform Contracts are locked. Endpoints evolve. Backends scale. But the SDK surface never breaks. Every tool can count on stable, versioned Capability APIs.\n\n---\n\n## Integration with Recovery Vision\n\nThe **Human Workbench Recovery** + **Platform Activation** are not competing—they're complementary:\n\n**Recovery Vision:**\n- Human Workbench is primary\n- 8 Workbench lenses (Sales, CS, Finance, Ops, etc.)\n- Surfaces are configurable features\n- AI Twin has separate home\n\n**Platform Activation:**\n- Same 8 lenses become Projections\n- Each Projection calls iw.workbench.lens(LensName)\n- Capability SDK is universal\n- Any frontend can implement any Projection\n\n**Together:** When both are done, you've proven:\n1. ✓ The workbench is human-centric (Recovery)\n2. ✓ The workbench is a platform, not a tool (Platform Activation)\n3. ✓ Business logic is in Capabilities, not UIs (Platform)\n4. ✓ Any frontend can become IntegrateWise (Activation)\n\n---\n\n*Framework: Platform Activation*\n*Status: Frozen Architecture, Roadmap Defined*\n*Next: Begin Phase A backend completion*\n"}