{"slug":"architecture/MICROFRONTENDS","title":"IntegrateWise Microfrontends","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/MICROFRONTENDS.mdx","bytes":14727,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Implementation reference\n**Date:** 2026-08-02\n**Authority:** [INTEGRATEWISE_ARCHITECTURE.md](INTEGRATEWISE_ARCHITECTURE.md)\n**Visual companion:** [final-architecture.html](../final-architecture.html)\n\n---\n\n## Canonical principle\n\nIntegrateWise owns the **Platform Kernel** (Spine, ADK, Discovery Engine, Capability Resolver, Loader, Normalizer, Projection Engine). Everything else — authentication, connectors, tools, models, agents, skills, workflow runtimes — is **inherited from the connected host**.\n\nThree host-neutral, composable microfrontends provide invokable surfaces. Any host (IntegrateWise Web, Platform, ChatGPT, Claude, MCP Client, Agent Runtime, External App) can invoke them.\n\n---\n\n## OneAuth → Total Continuity\n\n**The core product vision.** One connection per host. Entire ecosystem discovers. No N×M re-connections.\n\n### The problem\n\nToday, every host (ChatGPT, Claude, DIA, etc.) requires its own set of OAuth connections. If ChatGPT is connected to 50 apps and Claude is connected to 50 apps, the user must authenticate separately for each host × each app. This is N×M complexity.\n\n### The solution\n\n```\nUser connects once (e.g. via ChatGPT: 50 apps)\n  → OneAuth establishes identity + host context\n  → Spine hydrates\n  → Discovery Engine discovers all 50 connected apps from host\n  → Connectors projected (not re-connected)\n  → User sees data from all 50 apps immediately\n\nUser connects again (e.g. via Claude: different 50 apps)\n  → Same OneAuth, same Spine\n  → Claude's 50 apps also discovered\n  → DIA's 3-4 apps also discovered\n\nResult: N hosts × M apps = N+M connections (not N×M)\n  → One connection per host, entire ecosystem discovers\n```\n\n### Core principles\n\n| Principle                          | Meaning                                                                                            |\n| ---------------------------------- | -------------------------------------------------------------------------------------------------- |\n| **Connectors are projections**     | IntegrateWise owns zero connectors. They are projections of the host environment                   |\n| **OneAuth = single entry**         | One identity → Spine hydrates → all host connections discovered                                    |\n| **Spine = communication layer**    | Claude's data accessible via Spine. ChatGPT's work visible via Spine. Agent-to-agent through Spine |\n| **User sees workbench only**       | Behind the scene: agents, Spine, discovery, memory, tool data — all invisible                      |\n| **Twin = context on click**        | User clicks → Twin already has context → surfaces evidence instantly                               |\n| **OODA + Pipeline = search/fetch** | Pipeline stages in Spine Cache determine how to search, fetch, surface                             |\n\n### How it works end-to-end\n\n```text\n1. User arrives from Host X (ChatGPT, Claude, DIA, Web, Platform, etc.)\n2. OneAuth establishes identity + host context\n3. Spine hydrates (canonical truth loaded)\n4. Discovery Engine discovers host's connected apps\n5. Connector tray = projections from host (not a catalog)\n6. User works in workbench — sees data from all connected apps\n7. Twin has context of everything — surfaces on click\n8. Agent-to-agent communication via Spine (Claude's work visible to ChatGPT)\n9. Tool memory, tool data surfaced through Spine Cache\n10. User never sees the infrastructure — only the workbench\n```\n\n### What IntegrateWise owns vs inherits\n\n| IntegrateWise owns      | Inherited from host   |\n| ----------------------- | --------------------- |\n| OneAuth (identity)      | OAuth connections     |\n| Spine (canonical truth) | Provider credentials  |\n| ADK (agent contracts)   | Tool implementations  |\n| Discovery Engine        | Connected apps        |\n| Capability Resolver     | Tool capabilities     |\n| Loader + Normalizer     | Provider data formats |\n| Projection Engine       | Host-specific UI      |\n| Orchestrator            | Agent runtimes        |\n| Agent Memory            | Tool memory           |\n| Skills                  | Host-native skills    |\n\n### Connection model\n\n```text\nHost A (ChatGPT: 50 apps)\n  → OneAuth → Spine → Discovery → 50 connectors projected\n\nHost B (Claude: 50 apps)\n  → Same OneAuth → Same Spine → 50 more connectors projected\n\nHost C (DIA: 3 apps)\n  → Same OneAuth → Same Spine → 3 more connectors projected\n\nTotal: 3 hosts, 103 apps, 3 connections (not 309)\n```\n\n---\n\n## Three microfrontends\n\n| #   | Package                        | npm name                             | Role                                                                       | Status        |\n| --- | ------------------------------ | ------------------------------------ | -------------------------------------------------------------------------- | ------------- |\n| 1   | `packages/auth-connectors-mfe` | `@integratewise/auth-connectors-mfe` | Universal identity, grants, discovery, connector tray, capability matrices | ✅ Scaffolded |\n| 2   | `packages/auth-onboarding-mfe` | `@integratewise/auth-onboarding-mfe` | Login / signup / onboarding flow                                           | ✅ Scaffolded |\n| 3   | `packages/platform-mfe`        | `@integratewise/platform-mfe`        | Platform Control Board — all kernel features                               | ✅ Scaffolded |\n\n---\n\n## 1. Auth + Connectors MFE\n\n**Purpose:** Universal identity, connection management, discovery, and capability-access layer.\n\n**Not bound to the platform** — consumable by any host:\n\n- apps/web, apps/platform\n- Twin Orchestrator, platform agents\n- ChatGPT, Claude, MCP clients\n- Plugin hosts, external applications\n- Agent runtimes\n\n### Surfaces\n\n| Surface         | Description                                                      |\n| --------------- | ---------------------------------------------------------------- |\n| `/auth`         | Login, signup, OAuth, session management                         |\n| `/connectors`   | Connector tray — projections from connected host                 |\n| `/marketplace`  | Connector marketplace (browsable unauthenticated)                |\n| `/discovery`    | Host discovery results                                           |\n| `/grants`       | Scoped access grants                                             |\n| `/capabilities` | Capability matrix, connected-tool matrix, tool-capability matrix |\n| `/spine`        | Business context with connected/tool-capability matrices         |\n\n### Architecture\n\n```\nHost connection context\n  → One Auth establishes identity + host\n  → Discovery Engine discovers host resources\n  → Connector tray = projections from host\n  → Capabilities resolved from host tools\n  → User sees only what host provides\n```\n\n**Host is detected during onboarding, not selected at runtime.**\n\n### Key components\n\n- `AuthConnectorsProvider` — context provider with auth + connector state\n- `AuthConnectorsShell` — main container\n- `LoginForm` / `SignUpForm` — authentication forms\n- `OAuthButtons` — Google, GitHub, Microsoft, Slack\n- `ConnectorCatalog` — host-projected connector grid\n- `ConnectorCard` — individual connector display\n- `ConnectorInstallModal` — OAuth/API key installation flow\n- `OnboardingFlow` — multi-step wizard with host detection\n- `UserAvatar` — user display component\n- `AuthGuard` — route protection\n\n### Hooks\n\n- `useAuth()` — authentication state and actions\n- `useConnectors()` — connector state and actions\n- `useOnboarding()` — onboarding state\n- `useHostEnvironment()` — host environment (admin-only, not user-facing)\n\n---\n\n## 2. Auth + Onboarding MFE\n\n**Purpose:** Simplified login/signup/onboarding flow, independent of connector management.\n\n### Key components\n\n- `AuthOnboardingProvider` — simplified auth context (no connectors)\n- `LoginForm` / `SignUpForm` / `OAuthButtons` — authentication\n- `OnboardingFlow` — multi-step wizard\n- `AuthGuard` — route protection\n\n### Hooks\n\n- `useAuth()` — authentication state\n- `useOnboarding()` — onboarding state\n\n---\n\n## 3. Platform MFE\n\n**Purpose:** Platform Control Board — the complete control plane surface.\n\n### Kernel views (IntegrateWise-owned)\n\n| View                | Component                  | Description                                                                          |\n| ------------------- | -------------------------- | ------------------------------------------------------------------------------------ |\n| **Spine Fabric**    | `SpineFabricView`          | Operational DB fabric: cache ↔ canonical ↔ KV ↔ R2 ↔ Redis ↔ AI Search ↔ Omni Router |\n| **Spine Network**   | `SpineNetworkView`         | Visual graph of Spine nodes and edges                                                |\n| **OODA Pipeline**   | `OODAPipelineView`         | Observe → Orient → Decide → Act pipeline                                             |\n| **Agent Status**    | `AgentStatusView`          | 5 bounded agents + Co-worker status                                                  |\n| **Memory Queues**   | `MemoryQueuesView`         | Memory Queue + Approval Queue + Promotion Queue + 10 memory categories               |\n| **Tool Capability** | `ToolCapabilityMatrixView` | Host-connected tools → capabilities → workspace projection                           |\n| **Configuration**   | `ConfigurationManagerView` | Tenant, schema, connector, projection configuration                                  |\n| **Activation**      | `ActivationManagerView`    | Activation status, blockers, go-live checklist                                       |\n\n### Platform kernel (what IntegrateWise owns)\n\n```text\nIntegrateWise Platform Kernel\n├── Spine (canonical tenant truth)\n├── Spine Schema\n├── Business Context\n├── ADK (Agent Development Kit)\n├── Discovery Engine\n├── Capability Resolver\n├── Loader\n├── Normalizer\n├── Schema Mapping\n├── Reconciliation\n├── Projection Engine\n└── Workspace Composition\n```\n\n### Agents (5 bounded)\n\n| Agent                   | Role                           | User-facing           |\n| ----------------------- | ------------------------------ | --------------------- |\n| **Twin**                | Communicator + Orchestrator    | ✅ Yes                |\n| **Triage**              | Communicator + Router          | ✅ Yes (through Twin) |\n| **Schema Generator**    | Internal — schema proposals    | ❌ Internal           |\n| **Schema Orchestrator** | Internal — schema lifecycle    | ❌ Internal           |\n| **Auto-Tuner**          | Internal — system optimization | ❌ Internal           |\n| **Co-worker**           | Execution worker               | ❌ Internal           |\n\n### Memory system (10 categories)\n\n| Category          | Authority                     | Retention                   |\n| ----------------- | ----------------------------- | --------------------------- |\n| Operational       | Spine canonical writer        | Durable                     |\n| Event / Episodic  | Event runtime                 | Durable / policy            |\n| Work / Continuity | Continuity runtime            | Until closure + policy      |\n| Twin              | Memory service                | Versioned, revocable        |\n| Session           | Twin runtime                  | Retention-controlled        |\n| Organizational    | Triage/promotion + governance | Durable, versioned          |\n| Knowledge         | Knowledge service             | Rebuildable from sources    |\n| Audit             | Governance                    | Append-only, high retention |\n| Artifact          | Object storage                | Retention / classification  |\n| Retrieval / Cache | Projection / runtime          | Disposable, rebuildable     |\n\n### Spine Fabric\n\nThe operational database fabric connecting:\n\n- **Spine Cache** — operational DB (hot data)\n- **Canonical Spine** — source of truth\n- **KV Store** — configuration and session state\n- **R2 Storage** — object blobs (documents, artifacts)\n- **Redis** — hot cache and pub/sub\n- **AI Search** — vector + FTS (1536 dimensions)\n- **Omni Router** — multi-protocol routing\n\n### Data flow tunnel\n\n```\nHost Tools → Loader → Normalizer → Spine Cache → Canonical Spine → Projection Engine → Workspace\n```\n\n---\n\n## Design tokens\n\nAll three MFEs use `packages/*/src/lib/design-tokens.ts` as the single source of truth for colors, spacing, typography, and shadows. Derived from `apps/web/src/integratewise-figma-tokens.json`.\n\n### Color palette\n\n| Token         | Value                    | Usage                         |\n| ------------- | ------------------------ | ----------------------------- |\n| `primary`     | `#5b814f` (Forest Green) | Actions, links, active states |\n| `background`  | `#f7f6f2` (Paper)        | Page background               |\n| `foreground`  | `#0c0c0c` (Ink)          | Primary text                  |\n| `card`        | `#f0ede7` (Paper Warm)   | Card backgrounds              |\n| `border`      | `#c8c3b8` (Rule)         | Borders and dividers          |\n| `goldAccent`  | `#b8943f` (Gold)         | Complementary accent          |\n| `destructive` | `#d03131` (Red)          | Errors and warnings           |\n\n---\n\n## Host detection architecture\n\nThe host is **identified during onboarding/activation**, not selected at runtime:\n\n1. User arrives from Host X (ChatGPT, Claude, Web, Platform, MCP Client, etc.)\n2. One Auth establishes identity + host context\n3. Discovery Engine runs against Host X\n4. Connector tray = projections from Host X\n5. User sees only what Host X provides\n\nThe `HostSelector` component exists for **admin/configuration** use only — visible in the Configuration Manager, not to end users.\n\n---\n\n## Composition\n\nComposed surfaces (microfrontend + platform):\n\n- Platform + Web (Customer Zero workbench)\n- Platform + Ops (operational view)\n- Web standalone (marketing + business app)\n- MCP Client thin client\n- ChatGPT/Claude plugin host\n\nEach is a microfrontend if not a separate deployment.\n\n---\n\n## Build order\n\n1. **Phase 1** — Contracts & shell: workspace route, projection-driven sidebar, Home, My Work, Twin drawer\n2. **Phase 2** — Operational UI: Configuration Manager, Activation Manager, Discovery Engine, Capability Explorer\n3. **Phase 3** — Network visualization: Spine Network, Agent Communication, Tool Execution Graph\n4. **Phase 4** — Workbench integration: contextual capability dock, invocation, approval cards\n5. **Phase 5** — Cross-repo SDK: `@integratewise/*` packages so channel repos consume, never copy\n"}