{"slug":"architecture/PLATFORM_CONTROL_SURFACE_MAPPING","title":"apps/platform — Frontend ↔ Backend Canonical Mapping","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/PLATFORM_CONTROL_SURFACE_MAPPING.mdx","bytes":21275,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n`apps/platform` is the **Platform Control Surface**. It does not contain the backend implementations it controls.\n\n```text\napps/platform\n      ↓\nGateway / TenantGate\n      ↓\nPlatform APIs\n      ↓\nCanonical backend services\n      ↓\nSpine / Runtime / Providers\n```\n\nThe governing rule is:\n\n> **Platform UI observes, configures and governs the runtime. Backend services own execution and state.**\n\n---\n\n## 1. Top-level platform architecture\n\n```text\n┌────────────────────────────────────────────┐\n│              apps/platform                 │\n│                                            │\n│ Integration Manager                        │\n│ Connector Marketplace                      │\n│ Activation Hub                             │\n│ Capability Manager                         │\n│ MCP Pool                                   │\n│ AI Models                                  │\n│ Knowledge                                  │\n│ Memory & Continuity                        │\n│ Automation                                 │\n│ Pipelines                                  │\n│ Governance                                 │\n│ Observability                              │\n│ Administration                             │\n└───────────────────┬────────────────────────┘\n                    │\n                    ▼\n          Gateway / Platform API\n                    │\n      ┌─────────────┼────────────────┐\n      ▼             ▼                ▼\n services/*     packages/*       contracts/*\n      │\n      ▼\n Canonical + Operational Runtime\n      │\n      ├── Neon\n      ├── D1\n      ├── KV\n      ├── Durable Objects\n      ├── R2\n      ├── Vectorize / Search\n      ├── Queues / Workflows\n      ├── AI Gateway\n      ├── MCP\n      └── External Providers\n```\n\n---\n\n# 2. Canonical frontend/backend mapping\n\n| Platform frontend     | Primary backend               | Supporting backend                    | Main state                |\n| --------------------- | ----------------------------- | ------------------------------------- | ------------------------- |\n| Integration Manager   | `services/connectors`         | loader, normalizer, spine-sync        | Neon + D1                 |\n| Connector Marketplace | marketplace registry          | connector service, capability service | registry/config           |\n| Activation Hub        | activation/workspace runtime  | connectors, spine-sync, capability    | D1 + Neon                 |\n| Capability Manager    | `services/capability`         | governance, connectors                | definitions/policies      |\n| MCP Pool              | MCP runtime/router            | capability, governance                | MCP registry/runtime      |\n| AI Models             | intelligence/model runtime    | AI Gateway, policy                    | model/provider config     |\n| Knowledge             | `services/knowledge`          | loader, pipeline, search              | R2 + Vectorize + metadata |\n| Memory & Continuity   | `services/memory`             | intelligence, governance, pipeline    | D1 + Neon                 |\n| Automation            | orchestrator/workflow runtime | capability, governance, queues        | workflow state            |\n| Pipelines             | loader/normalizer/pipeline    | spine-sync, reconciliation            | D1 + Neon                 |\n| Governance            | `services/governance`         | capability, orchestrator              | proposals/approvals/audit |\n| Observability         | `services/observability`      | all services                          | telemetry                 |\n| Administration        | tenant/auth/admin services    | billing/security/deployment           | canonical config          |\n\n---\n\n# 3. Integration Manager\n\nFrontend:\n\n```text\napps/platform\n└── Integration Manager\n    ├── Connections\n    ├── Providers\n    ├── Scopes\n    ├── Sync Status\n    ├── Health\n    ├── Mapping\n    ├── Errors\n    └── Repair\n```\n\nBackend:\n\n```text\nIntegration Manager UI\n        ↓\nGateway\n        ↓\nservices/connectors\n        │\n        ├── host connection projections\n        ├── connector registry\n        ├── provider adapters\n        ├── webhook state\n        ├── sync cursors\n        └── connection health\n        │\n        ├── services/loader\n        ├── services/normalizer\n        └── services/spine-sync\n```\n\nData flow:\n\n```text\nProvider\n→ Connector\n→ Loader\n→ Normalizer\n→ Canonical Spine / Neon\n→ Spine Sync\n→ Operational Spine / D1\n```\n\n### Frontend may\n\n```text\nview connection\nenable/disable\nconfigure permitted scopes\nstart sync\ntest connection\ninspect health\nrepair/retry\n```\n\n### Frontend may not\n\n```text\ndirectly hold OAuth secrets\ndirectly call provider APIs for product actions\nwrite Canonical Spine\n```\n\n---\n\n# 4. Connector Marketplace\n\nFrontend:\n\n```text\nConnector Marketplace\n├── Available\n├── Installed\n├── Categories\n├── Provider Details\n├── Required Scopes\n├── Capabilities\n└── Install / Activate\n```\n\nBackend:\n\n```text\napps/platform\n→ marketplace/\n→ services/connectors\n→ services/capability\n→ OneAuth / host policy\n```\n\nImportant separation:\n\n```text\nMarketplace\n= what can be installed\n\nIntegration Manager\n= what is actually connected/configured\n\nCapability Manager\n= what the connection allows the workspace to do\n```\n\n---\n\n# 5. Activation Hub\n\nFrontend:\n\n```text\nActivation Hub\n├── Identity\n├── Workspace\n├── Connections\n├── Package\n├── Spine Hydration\n├── Workbench\n└── Readiness\n```\n\nBackend:\n\n```text\nActivation Hub\n   ↓\nWorkspace Activation Service\n   ├── OneAuth\n   ├── Discovery\n   ├── Integration Manager\n   ├── Capability Resolver\n   ├── Loader\n   ├── Normalizer\n   ├── Spine Sync\n   └── Projection Service\n```\n\nCanonical lifecycle:\n\n```text\nAuthenticate\n→ Resolve tenant/workspace\n→ Discover host connections\n→ Activate connector projections\n→ Resolve capabilities\n→ Load\n→ Normalize\n→ Canonical Spine\n→ Hydrate Operational Spine\n→ Compile Workbench\n→ Readiness\n```\n\n---\n\n# 6. Capability Manager\n\nThis is one of the most important mappings.\n\nFrontend:\n\n```text\nCapability Manager\n├── Capability Catalog\n├── Effective Capabilities\n├── Provider Bindings\n├── Policies\n├── Risk\n├── Approval Requirement\n└── Availability\n```\n\nBackend ownership:\n\n```text\npackages/capability\n        ↓ contracts\n\nservices/capability\n        ↓ runtime\n\nservices/governance\n        ↓ authority\n\nservices/connectors / mcp\n        ↓ implementation\n```\n\nCanonical chain:\n\n```text\nBusiness Capability\n       ↓\nCapability Policy\n       ↓\nProvider Binding\n       ├── REST\n       ├── MCP\n       ├── Native\n       └── Internal\n```\n\nExample:\n\n```text\nsales.opportunity.update\n```\n\nmay bind to:\n\n```text\nSalesforce REST\nHubSpot API\nMCP tool\nInternal service\n```\n\nFrontend never authorizes directly from raw MCP scopes.\n\n---\n\n# 7. MCP Pool\n\nFrontend:\n\n```text\nMCP Pool\n├── Servers\n├── Connections\n├── Tools\n├── Health\n├── Sessions\n├── Tool Discovery\n├── Capability Bindings\n└── Diagnostics\n```\n\nBackend:\n\n```text\napps/platform\n→ MCP management API\n→ mcp/\n→ apps/mcp-servers / managed runtime\n→ Capability Resolver\n→ Governance\n```\n\nImportant:\n\n```text\nMCP tool\n≠ business capability\n\nMCP scope\n≠ role permission\n```\n\nCorrect:\n\n```text\nBusiness Capability\n→ Capability Binding\n→ MCP Tool\n```\n\n---\n\n# 8. AI Models\n\nFrontend:\n\n```text\nAI Models\n├── Providers\n├── Models\n├── Availability\n├── Routing\n├── Cost\n├── Latency\n├── Health\n└── Policy\n```\n\nBackend:\n\n```text\napps/platform\n→ services/intelligence\n→ AI Gateway\n→ provider registry\n→ model routing policy\n```\n\nSupporting contracts:\n\n```text\npackages/intelligence\n├── IntelligenceProfile\n├── skills\n├── reasoning policy\n└── proposal policy\n```\n\nThe platform UI configures model availability.\n\nThe Workbench should not expose provider/model selection as normal user workflow.\n\n---\n\n# 9. Knowledge\n\nFrontend:\n\n```text\nKnowledge\n├── Sources\n├── Documents\n├── Evidence\n├── Index Status\n├── Entity Links\n├── Search\n├── Freshness\n└── Re-index\n```\n\nBackend:\n\n```text\nservices/knowledge\n├── R2\n├── metadata\n├── Vectorize\n├── AI Search\n├── Spine relationships\n└── ingestion pipeline\n```\n\nFlow:\n\n```text\nSource\n→ Loader\n→ Knowledge ingestion\n→ R2\n→ extraction/index\n→ Vectorize/Search\n→ Spine evidence relationship\n```\n\nTruth distinction:\n\n```text\nR2\n= evidence/blob\n\nVectorize/Search\n= retrieval\n\nSpine\n= relationship/provenance\n\nNeither Search nor R2 becomes canonical business truth.\n```\n\n---\n\n# 10. Memory & Continuity\n\nFrontend:\n\n```text\nMemory & Continuity\n├── Working Memory\n├── Memory Candidates\n├── Promoted Memory\n├── Scope\n├── Sources\n├── Evidence\n├── Promotion Status\n├── Continuity Timeline\n└── Retention\n```\n\nBackend:\n\n```text\nservices/memory\n      ↓\nservices/governance\n      ↓\nservices/pipeline\n```\n\nStorage:\n\n```text\nD1\n= operational / working memory\n\nNeon\n= approved durable memory\n\nKV / DO\n= hot/session context\n```\n\nLifecycle:\n\n```text\nObservation\n→ Working Memory\n→ Candidate\n→ Policy\n→ Approval if required\n→ Durable Memory\n```\n\nTwin can create/propose memory candidates.\n\nTwin does not directly write durable organizational memory.\n\n---\n\n# 11. Automation\n\nFrontend:\n\n```text\nAutomation\n├── Triggers\n├── Schedules\n├── Workflows\n├── Runs\n├── Failures\n├── Retry\n├── Actions\n└── History\n```\n\nBackend:\n\n```text\nAutomation UI\n→ services/orchestrator\n→ services/capability\n→ services/governance\n→ Cloudflare Queues / Workflows\n→ provider execution\n→ reconciliation\n```\n\nExecution:\n\n```text\nTrigger\n→ Orchestrator\n→ Capability Resolver\n→ Governance\n→ Workflow\n→ Provider\n→ Outcome\n→ Reconciliation\n```\n\n---\n\n# 12. Pipelines\n\nFrontend:\n\n```text\nPipelines\n├── Sources\n├── Runs\n├── Loader\n├── Normalization\n├── Validation\n├── Errors\n├── Rejected Records\n├── Replay\n├── Promotion\n└── Reconciliation\n```\n\nBackend:\n\n```text\nservices/loader\n      ↓\nservices/normalizer\n      ↓\nservices/pipeline\n      ↓\nCanonical Spine\n      ↓\nservices/spine-sync\n      ↓\nOperational Spine\n```\n\nThe Platform UI controls/observes pipeline state.\n\nIt does not implement the pipeline.\n\n---\n\n# 13. Spine Sync\n\nThis should probably appear inside Pipelines/Operational Health rather than as another top-level product concept.\n\nFrontend status:\n\n```text\nSpine Sync\n├── Hydration\n├── Freshness\n├── Lag\n├── Stale Entities\n├── Promotions\n├── Reconciliation Failures\n└── Operational Working Set\n```\n\nBackend:\n\n```text\nservices/spine-sync\n├── hydrate()\n├── refresh()\n├── invalidate()\n├── promote()\n├── reconcile()\n└── evict()\n```\n\nRuntime:\n\n```text\nCanonical Spine — Neon\n        ↕\n      Spine Sync\n        ↕\nOperational Spine — D1\n```\n\n---\n\n# 14. Governance\n\nFrontend:\n\n```text\nGovernance\n├── Proposals\n├── Pending Approvals\n├── Policies\n├── Rules\n├── Risk\n├── Exceptions\n├── Decisions\n├── Execution Effects\n└── Audit\n```\n\nBackend:\n\n```text\nservices/governance\n├── principal evaluation\n├── policy evaluation\n├── risk\n├── approval state\n├── evidence\n├── proposed effects\n└── decision ledger\n```\n\nExecution after approval:\n\n```text\nGovernance\n→ Orchestrator\n→ Capability\n→ Provider\n→ Reconciliation\n```\n\nGovernance determines **whether** something may happen.\n\nIt does not perform the provider action.\n\n---\n\n# 15. Observability\n\nFrontend:\n\n```text\nObservability\n├── Platform Health\n├── Service Health\n├── Connector Health\n├── Pipeline Health\n├── Projection Freshness\n├── Spine Sync\n├── AI Usage\n├── Agent Runs\n├── Capability Execution\n├── Errors\n├── Latency\n└── Cost\n```\n\nBackend aggregates from:\n\n```text\nGateway\nContext\nProjection\nLoader\nNormalizer\nPipeline\nSpine Sync\nCapability\nGovernance\nOrchestrator\nConnectors\nIntelligence\nMemory\nKnowledge\nReconciliation\n```\n\nCanonical backend:\n\n```text\nservices/observability\n```\n\n---\n\n# 16. Administration\n\nFrontend:\n\n```text\nAdministration\n├── Organizations\n├── Workspaces\n├── Users\n├── Roles\n├── Permissions\n├── Audit\n├── Billing\n├── Deployments\n├── API Keys\n├── Security\n├── Admin\n└── Paywall\n```\n\nBackend mapping:\n\n| UI            | Backend authority              |\n| ------------- | ------------------------------ |\n| Organizations | tenant/org service             |\n| Workspaces    | workspace service              |\n| Users         | OneAuth + membership           |\n| Roles         | RBAC                           |\n| Permissions   | authorization policy           |\n| Audit         | audit ledger                   |\n| Billing       | billing service                |\n| Deployments   | deployment/runtime control     |\n| API Keys      | credential management          |\n| Security      | security policy                |\n| Admin         | tenant/platform administration |\n| Paywall       | entitlement/billing policy     |\n\n---\n\n# 17. Platform frontend route structure\n\nA reasonable canonical frontend layout is:\n\n```text\napps/platform/\n└── app/\n    ├── integration-manager/\n    ├── connector-marketplace/\n    ├── activation/\n    ├── capabilities/\n    ├── mcp/\n    ├── ai-models/\n    ├── knowledge/\n    ├── memory/\n    ├── automation/\n    ├── pipelines/\n    ├── governance/\n    ├── observability/\n    │\n    └── administration/\n        ├── organizations/\n        ├── workspaces/\n        ├── users/\n        ├── roles/\n        ├── permissions/\n        ├── audit/\n        ├── billing/\n        ├── deployments/\n        ├── api-keys/\n        ├── security/\n        ├── admin/\n        └── paywall/\n```\n\nThis is UI structure only.\n\n---\n\n# 18. Backend service structure\n\nCorresponding runtime:\n\n```text\nservices/\n├── gateway/\n├── activation/\n├── connectors/\n├── loader/\n├── normalizer/\n├── context/\n├── projection/\n├── spine-sync/\n├── pipeline/\n├── capability/\n├── governance/\n├── orchestrator/\n├── reconciliation/\n├── knowledge/\n├── memory/\n├── intelligence/\n└── observability/\n```\n\nYou may not need an independently deployed Worker for every directory immediately. The **ownership boundary** should still exist even where multiple modules initially share one Worker deployment.\n\n---\n\n# 19. Packages versus services versus platform\n\nThis distinction should be frozen:\n\n```text\npackages/*\n= definitions / contracts / reusable semantics\n\nservices/*\n= runtime implementations\n\napps/platform/*\n= configuration + control + observation UI\n```\n\nExample:\n\n```text\npackages/capability\n        ↓\ndefines \"sales.opportunity.update\"\n\nservices/capability\n        ↓\nresolves effective implementation\n\napps/platform/capabilities\n        ↓\nallows authorized operator to inspect/configure it\n```\n\n---\n\n# 20. Read path\n\nFor any Platform page:\n\n```text\napps/platform\n      ↓\nOneAuth Principal\n      ↓\nGateway / TenantGate\n      ↓\nPlatform API\n      ↓\nBackend service\n      ↓\nCanonical / Operational state\n      ↓\nDTO / Control View\n      ↓\napps/platform\n```\n\nExample:\n\n```text\nIntegration Manager\n→ GET connection state\n→ Gateway\n→ Connector Service\n→ D1 + Canonical configuration\n→ ConnectionStatus[]\n→ Platform UI\n```\n\n---\n\n# 21. Configuration/write path\n\nPlatform configuration changes follow:\n\n```text\nPlatform UI\n      ↓\nCommand\n      ↓\nGateway\n      ↓\nPermission evaluation\n      ↓\nOwning service\n      ↓\nGovernance where consequential\n      ↓\nPipeline / configuration writer\n      ↓\nCanonical configuration\n      ↓\nRuntime invalidation / refresh\n      ↓\nPlatform UI\n```\n\nFor example:\n\n```text\nEnable capability\n→ capability.configure\n→ permission\n→ capability service\n→ policy validation\n→ Canonical config\n→ cache invalidation\n→ capability resolver refresh\n```\n\n---\n\n# 22. Operational action path\n\nFor actions against external providers:\n\n```text\napps/platform\n      ↓\nCapability command\n      ↓\nCapability Resolver\n      ↓\nGovernance\n      ↓\nOrchestrator\n      ↓\nConnector / MCP / API\n      ↓\nProvider result\n      ↓\nRe-ingestion\n      ↓\nReconciliation\n      ↓\nCanonical Spine\n      ↓\nOperational refresh\n      ↓\nPlatform status update\n```\n\nThis must remain separate from simple platform configuration writes.\n\n---\n\n# 23. Platform frontend/backend manifest\n\nEach Platform surface should eventually have a mapping contract such as:\n\n```ts\ninterface PlatformSurfaceMapping {\n  id: string;\n  route: string;\n\n  readService: string;\n  readContract: string;\n\n  commands: string[];\n\n  permissions: string[];\n\n  canonicalState?: string[];\n  operationalState?: string[];\n\n  backendOwner: string;\n\n  governance?: \"none\" | \"conditional\" | \"required\";\n}\n```\n\nExample:\n\n```ts\n{\n  id: \"platform.integration-manager\",\n  route: \"/integration-manager\",\n\n  readService: \"connectors\",\n  readContract: \"ConnectionInventory\",\n\n  commands: [\n    \"connection.enable\",\n    \"connection.disable\",\n    \"connection.sync\",\n    \"connection.test\"\n  ],\n\n  permissions: [\n    \"platform.connections.read\",\n    \"platform.connections.manage\"\n  ],\n\n  canonicalState: [\n    \"connector configuration\",\n    \"sync policy\"\n  ],\n\n  operationalState: [\n    \"connection health\",\n    \"sync cursor\",\n    \"latest run\"\n  ],\n\n  backendOwner: \"services/connectors\",\n\n  governance: \"conditional\"\n}\n```\n\n---\n\n# 24. Full Platform vertical mapping\n\n```text\n                         apps/platform\n                               │\n                               ▼\n                    PLATFORM CONTROL SURFACE\n                               │\n       ┌───────────────────────┼────────────────────────┐\n       │                       │                        │\n   Configuration           Operations              Governance\n       │                       │                        │\n       └───────────────────────┼────────────────────────┘\n                               ▼\n                     Gateway / TenantGate\n                               │\n                               ▼\n                       Platform APIs\n                               │\n       ┌───────────────────────┼──────────────────────────┐\n       ▼                       ▼                          ▼\n  Connectors              Capability                 Intelligence\n  Activation              Governance                 Knowledge\n  Pipeline                Orchestrator               Memory\n  Spine Sync              Reconciliation             Observability\n       │                       │                          │\n       └───────────────────────┼──────────────────────────┘\n                               ▼\n                        Runtime Substrates\n                               │\n             ┌─────────────────┼────────────────┐\n             ▼                 ▼                ▼\n         Neon/D1            R2/Search        KV/DO\n             │\n             ▼\n                  Connector / MCP / Provider\n```\n\n## Final platform rule\n\n```text\napps/platform\n= control surface\n\npackages/*\n= product contracts\n\nservices/*\n= backend ownership\n\nNeon\n= canonical configuration/truth\n\nD1\n= active operational/runtime state\n\nGateway\n= authenticated/authorized ingress\n\nGovernance\n= authority\n\nOrchestrator\n= approved coordination\n\nProvider\n= actual external action\n\nReconciliation\n= verified outcome\n```\n\nThis is the frontend ↔ backend mapping that should sit next to `CANONICAL_REPO_TOPOLOGY.md` as the canonical **Platform Control Surface Mapping**.\n"}