Unclassified
apps/platform — Frontend ↔ Backend Canonical Mapping
apps/platform is the Platform Control Surface. It does not contain the backend implementations it controls.
apps/platform
↓
Gateway / TenantGate
↓
Platform APIs
↓
Canonical backend services
↓
Spine / Runtime / Providers
The governing rule is:
Platform UI observes, configures and governs the runtime. Backend services own execution and state.
1. Top-level platform architecture
┌────────────────────────────────────────────┐
│ apps/platform │
│ │
│ Integration Manager │
│ Connector Marketplace │
│ Activation Hub │
│ Capability Manager │
│ MCP Pool │
│ AI Models │
│ Knowledge │
│ Memory & Continuity │
│ Automation │
│ Pipelines │
│ Governance │
│ Observability │
│ Administration │
└───────────────────┬────────────────────────┘
│
▼
Gateway / Platform API
│
┌─────────────┼────────────────┐
▼ ▼ ▼
services/* packages/* contracts/*
│
▼
Canonical + Operational Runtime
│
├── Neon
├── D1
├── KV
├── Durable Objects
├── R2
├── Vectorize / Search
├── Queues / Workflows
├── AI Gateway
├── MCP
└── External Providers
2. Canonical frontend/backend mapping
| Platform frontend | Primary backend | Supporting backend | Main state |
|---|---|---|---|
| Integration Manager | services/connectors | loader, normalizer, spine-sync | Neon + D1 |
| Connector Marketplace | marketplace registry | connector service, capability service | registry/config |
| Activation Hub | activation/workspace runtime | connectors, spine-sync, capability | D1 + Neon |
| Capability Manager | services/capability | governance, connectors | definitions/policies |
| MCP Pool | MCP runtime/router | capability, governance | MCP registry/runtime |
| AI Models | intelligence/model runtime | AI Gateway, policy | model/provider config |
| Knowledge | services/knowledge | loader, pipeline, search | R2 + Vectorize + metadata |
| Memory & Continuity | services/memory | intelligence, governance, pipeline | D1 + Neon |
| Automation | orchestrator/workflow runtime | capability, governance, queues | workflow state |
| Pipelines | loader/normalizer/pipeline | spine-sync, reconciliation | D1 + Neon |
| Governance | services/governance | capability, orchestrator | proposals/approvals/audit |
| Observability | services/observability | all services | telemetry |
| Administration | tenant/auth/admin services | billing/security/deployment | canonical config |
3. Integration Manager
Frontend:
apps/platform
└── Integration Manager
├── Connections
├── Providers
├── Scopes
├── Sync Status
├── Health
├── Mapping
├── Errors
└── Repair
Backend:
Integration Manager UI
↓
Gateway
↓
services/connectors
│
├── host connection projections
├── connector registry
├── provider adapters
├── webhook state
├── sync cursors
└── connection health
│
├── services/loader
├── services/normalizer
└── services/spine-sync
Data flow:
Provider
→ Connector
→ Loader
→ Normalizer
→ Canonical Spine / Neon
→ Spine Sync
→ Operational Spine / D1
Frontend may
view connection
enable/disable
configure permitted scopes
start sync
test connection
inspect health
repair/retry
Frontend may not
directly hold OAuth secrets
directly call provider APIs for product actions
write Canonical Spine
4. Connector Marketplace
Frontend:
Connector Marketplace
├── Available
├── Installed
├── Categories
├── Provider Details
├── Required Scopes
├── Capabilities
└── Install / Activate
Backend:
apps/platform
→ marketplace/
→ services/connectors
→ services/capability
→ OneAuth / host policy
Important separation:
Marketplace
= what can be installed
Integration Manager
= what is actually connected/configured
Capability Manager
= what the connection allows the workspace to do
5. Activation Hub
Frontend:
Activation Hub
├── Identity
├── Workspace
├── Connections
├── Package
├── Spine Hydration
├── Workbench
└── Readiness
Backend:
Activation Hub
↓
Workspace Activation Service
├── OneAuth
├── Discovery
├── Integration Manager
├── Capability Resolver
├── Loader
├── Normalizer
├── Spine Sync
└── Projection Service
Canonical lifecycle:
Authenticate
→ Resolve tenant/workspace
→ Discover host connections
→ Activate connector projections
→ Resolve capabilities
→ Load
→ Normalize
→ Canonical Spine
→ Hydrate Operational Spine
→ Compile Workbench
→ Readiness
6. Capability Manager
This is one of the most important mappings.
Frontend:
Capability Manager
├── Capability Catalog
├── Effective Capabilities
├── Provider Bindings
├── Policies
├── Risk
├── Approval Requirement
└── Availability
Backend ownership:
packages/capability
↓ contracts
services/capability
↓ runtime
services/governance
↓ authority
services/connectors / mcp
↓ implementation
Canonical chain:
Business Capability
↓
Capability Policy
↓
Provider Binding
├── REST
├── MCP
├── Native
└── Internal
Example:
sales.opportunity.update
may bind to:
Salesforce REST
HubSpot API
MCP tool
Internal service
Frontend never authorizes directly from raw MCP scopes.
7. MCP Pool
Frontend:
MCP Pool
├── Servers
├── Connections
├── Tools
├── Health
├── Sessions
├── Tool Discovery
├── Capability Bindings
└── Diagnostics
Backend:
apps/platform
→ MCP management API
→ mcp/
→ apps/mcp-servers / managed runtime
→ Capability Resolver
→ Governance
Important:
MCP tool
≠ business capability
MCP scope
≠ role permission
Correct:
Business Capability
→ Capability Binding
→ MCP Tool
8. AI Models
Frontend:
AI Models
├── Providers
├── Models
├── Availability
├── Routing
├── Cost
├── Latency
├── Health
└── Policy
Backend:
apps/platform
→ services/intelligence
→ AI Gateway
→ provider registry
→ model routing policy
Supporting contracts:
packages/intelligence
├── IntelligenceProfile
├── skills
├── reasoning policy
└── proposal policy
The platform UI configures model availability.
The Workbench should not expose provider/model selection as normal user workflow.
9. Knowledge
Frontend:
Knowledge
├── Sources
├── Documents
├── Evidence
├── Index Status
├── Entity Links
├── Search
├── Freshness
└── Re-index
Backend:
services/knowledge
├── R2
├── metadata
├── Vectorize
├── AI Search
├── Spine relationships
└── ingestion pipeline
Flow:
Source
→ Loader
→ Knowledge ingestion
→ R2
→ extraction/index
→ Vectorize/Search
→ Spine evidence relationship
Truth distinction:
R2
= evidence/blob
Vectorize/Search
= retrieval
Spine
= relationship/provenance
Neither Search nor R2 becomes canonical business truth.
10. Memory & Continuity
Frontend:
Memory & Continuity
├── Working Memory
├── Memory Candidates
├── Promoted Memory
├── Scope
├── Sources
├── Evidence
├── Promotion Status
├── Continuity Timeline
└── Retention
Backend:
services/memory
↓
services/governance
↓
services/pipeline
Storage:
D1
= operational / working memory
Neon
= approved durable memory
KV / DO
= hot/session context
Lifecycle:
Observation
→ Working Memory
→ Candidate
→ Policy
→ Approval if required
→ Durable Memory
Twin can create/propose memory candidates.
Twin does not directly write durable organizational memory.
11. Automation
Frontend:
Automation
├── Triggers
├── Schedules
├── Workflows
├── Runs
├── Failures
├── Retry
├── Actions
└── History
Backend:
Automation UI
→ services/orchestrator
→ services/capability
→ services/governance
→ Cloudflare Queues / Workflows
→ provider execution
→ reconciliation
Execution:
Trigger
→ Orchestrator
→ Capability Resolver
→ Governance
→ Workflow
→ Provider
→ Outcome
→ Reconciliation
12. Pipelines
Frontend:
Pipelines
├── Sources
├── Runs
├── Loader
├── Normalization
├── Validation
├── Errors
├── Rejected Records
├── Replay
├── Promotion
└── Reconciliation
Backend:
services/loader
↓
services/normalizer
↓
services/pipeline
↓
Canonical Spine
↓
services/spine-sync
↓
Operational Spine
The Platform UI controls/observes pipeline state.
It does not implement the pipeline.
13. Spine Sync
This should probably appear inside Pipelines/Operational Health rather than as another top-level product concept.
Frontend status:
Spine Sync
├── Hydration
├── Freshness
├── Lag
├── Stale Entities
├── Promotions
├── Reconciliation Failures
└── Operational Working Set
Backend:
services/spine-sync
├── hydrate()
├── refresh()
├── invalidate()
├── promote()
├── reconcile()
└── evict()
Runtime:
Canonical Spine — Neon
↕
Spine Sync
↕
Operational Spine — D1
14. Governance
Frontend:
Governance
├── Proposals
├── Pending Approvals
├── Policies
├── Rules
├── Risk
├── Exceptions
├── Decisions
├── Execution Effects
└── Audit
Backend:
services/governance
├── principal evaluation
├── policy evaluation
├── risk
├── approval state
├── evidence
├── proposed effects
└── decision ledger
Execution after approval:
Governance
→ Orchestrator
→ Capability
→ Provider
→ Reconciliation
Governance determines whether something may happen.
It does not perform the provider action.
15. Observability
Frontend:
Observability
├── Platform Health
├── Service Health
├── Connector Health
├── Pipeline Health
├── Projection Freshness
├── Spine Sync
├── AI Usage
├── Agent Runs
├── Capability Execution
├── Errors
├── Latency
└── Cost
Backend aggregates from:
Gateway
Context
Projection
Loader
Normalizer
Pipeline
Spine Sync
Capability
Governance
Orchestrator
Connectors
Intelligence
Memory
Knowledge
Reconciliation
Canonical backend:
services/observability
16. Administration
Frontend:
Administration
├── Organizations
├── Workspaces
├── Users
├── Roles
├── Permissions
├── Audit
├── Billing
├── Deployments
├── API Keys
├── Security
├── Admin
└── Paywall
Backend mapping:
| UI | Backend authority |
|---|---|
| Organizations | tenant/org service |
| Workspaces | workspace service |
| Users | OneAuth + membership |
| Roles | RBAC |
| Permissions | authorization policy |
| Audit | audit ledger |
| Billing | billing service |
| Deployments | deployment/runtime control |
| API Keys | credential management |
| Security | security policy |
| Admin | tenant/platform administration |
| Paywall | entitlement/billing policy |
17. Platform frontend route structure
A reasonable canonical frontend layout is:
apps/platform/
└── app/
├── integration-manager/
├── connector-marketplace/
├── activation/
├── capabilities/
├── mcp/
├── ai-models/
├── knowledge/
├── memory/
├── automation/
├── pipelines/
├── governance/
├── observability/
│
└── administration/
├── organizations/
├── workspaces/
├── users/
├── roles/
├── permissions/
├── audit/
├── billing/
├── deployments/
├── api-keys/
├── security/
├── admin/
└── paywall/
This is UI structure only.
18. Backend service structure
Corresponding runtime:
services/
├── gateway/
├── activation/
├── connectors/
├── loader/
├── normalizer/
├── context/
├── projection/
├── spine-sync/
├── pipeline/
├── capability/
├── governance/
├── orchestrator/
├── reconciliation/
├── knowledge/
├── memory/
├── intelligence/
└── observability/
You 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.
19. Packages versus services versus platform
This distinction should be frozen:
packages/*
= definitions / contracts / reusable semantics
services/*
= runtime implementations
apps/platform/*
= configuration + control + observation UI
Example:
packages/capability
↓
defines "sales.opportunity.update"
services/capability
↓
resolves effective implementation
apps/platform/capabilities
↓
allows authorized operator to inspect/configure it
20. Read path
For any Platform page:
apps/platform
↓
OneAuth Principal
↓
Gateway / TenantGate
↓
Platform API
↓
Backend service
↓
Canonical / Operational state
↓
DTO / Control View
↓
apps/platform
Example:
Integration Manager
→ GET connection state
→ Gateway
→ Connector Service
→ D1 + Canonical configuration
→ ConnectionStatus[]
→ Platform UI
21. Configuration/write path
Platform configuration changes follow:
Platform UI
↓
Command
↓
Gateway
↓
Permission evaluation
↓
Owning service
↓
Governance where consequential
↓
Pipeline / configuration writer
↓
Canonical configuration
↓
Runtime invalidation / refresh
↓
Platform UI
For example:
Enable capability
→ capability.configure
→ permission
→ capability service
→ policy validation
→ Canonical config
→ cache invalidation
→ capability resolver refresh
22. Operational action path
For actions against external providers:
apps/platform
↓
Capability command
↓
Capability Resolver
↓
Governance
↓
Orchestrator
↓
Connector / MCP / API
↓
Provider result
↓
Re-ingestion
↓
Reconciliation
↓
Canonical Spine
↓
Operational refresh
↓
Platform status update
This must remain separate from simple platform configuration writes.
23. Platform frontend/backend manifest
Each Platform surface should eventually have a mapping contract such as:
interface PlatformSurfaceMapping {
id: string;
route: string;
readService: string;
readContract: string;
commands: string[];
permissions: string[];
canonicalState?: string[];
operationalState?: string[];
backendOwner: string;
governance?: "none" | "conditional" | "required";
}
Example:
{
id: "platform.integration-manager",
route: "/integration-manager",
readService: "connectors",
readContract: "ConnectionInventory",
commands: [
"connection.enable",
"connection.disable",
"connection.sync",
"connection.test"
],
permissions: [
"platform.connections.read",
"platform.connections.manage"
],
canonicalState: [
"connector configuration",
"sync policy"
],
operationalState: [
"connection health",
"sync cursor",
"latest run"
],
backendOwner: "services/connectors",
governance: "conditional"
}
24. Full Platform vertical mapping
apps/platform
│
▼
PLATFORM CONTROL SURFACE
│
┌───────────────────────┼────────────────────────┐
│ │ │
Configuration Operations Governance
│ │ │
└───────────────────────┼────────────────────────┘
▼
Gateway / TenantGate
│
▼
Platform APIs
│
┌───────────────────────┼──────────────────────────┐
▼ ▼ ▼
Connectors Capability Intelligence
Activation Governance Knowledge
Pipeline Orchestrator Memory
Spine Sync Reconciliation Observability
│ │ │
└───────────────────────┼──────────────────────────┘
▼
Runtime Substrates
│
┌─────────────────┼────────────────┐
▼ ▼ ▼
Neon/D1 R2/Search KV/DO
│
▼
Connector / MCP / Provider
Final platform rule
apps/platform
= control surface
packages/*
= product contracts
services/*
= backend ownership
Neon
= canonical configuration/truth
D1
= active operational/runtime state
Gateway
= authenticated/authorized ingress
Governance
= authority
Orchestrator
= approved coordination
Provider
= actual external action
Reconciliation
= verified outcome
This is the frontend ↔ backend mapping that should sit next to CANONICAL_REPO_TOPOLOGY.md as the canonical Platform Control Surface Mapping.