{"slug":"internal/architecture/CANONICAL_REPO_TOPOLOGY","title":"IntegrateWise / SpineWorkspace — Canonical Repository Architecture","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/CANONICAL_REPO_TOPOLOGY.mdx","bytes":12465,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nThis is the frozen repository boundary specification.\n\n```text\nROOT\n│\n├── apps/\n│   → User-facing application surfaces and companion runtimes\n│\n├── packages/\n│   → Shared product/domain packages, schemas, configuration,\n│     MFEs, UI primitives and SDKs\n│\n├── services/\n│   → Backend runtimes, Cloudflare Workers, APIs and gateways\n│\n├── contracts/\n│   → Canonical protocol, API, event, schema and JSON contracts\n│\n├── configs/\n│   → Cross-repository environment, deployment and infrastructure configuration\n│\n├── marketplace/\n│   → Connector, MCP plugin and capability marketplace definitions\n│\n├── mcp/\n│   → MCP protocol bridges, definitions and server infrastructure\n│\n├── docs/\n│   → Canonical architecture, implementation specifications and ADRs\n│\n├── migrations/\n│   → Operational/distributed storage migrations\n│     D1 / KV / runtime state\n│\n├── sql-migrations/\n│   → Canonical Spine PostgreSQL migrations\n│     Neon / durable canonical state\n│\n└── tools/\n    → Importers, code generation, migration helpers and build tooling\n```\n\n## Domain Subdomains\n\n```text\nspineworkspace.com\n│\n├── www.spineworkspace.com          → Public marketing (apps/marketing)\n│\n├── auth.spineworkspace.com         → One Access (apps/one-access)\n├── connector.spineworkspace.com    → Connector management\n├── platform.spineworkspace.com     → Platform control plane (apps/platform)\n├── mcp.spineworkspace.com          → MCP infrastructure\n├── marketplace.spineworkspace.com  → Marketplace discovery\n├── admin.spineworkspace.com        → Administration\n│\n├── founder.spineworkspace.com      → Founder Workbench\n├── sales.spineworkspace.com        → Sales Workbench\n├── marketing.spineworkspace.com    → Marketing Workbench\n├── finance.spineworkspace.com      → Finance Workbench\n├── ops.spineworkspace.com          → Ops Workbench\n├── engineering.spineworkspace.com  → Engineering Workbench\n├── account-success.spineworkspace.com → TAM Workbench\n├── technical-account-success.spineworkspace.com → Technical Account Success\n├── business-intelligence.spineworkspace.com → Business Intelligence\n├── campaigns.spineworkspace.com    → Campaigns Workbench\n├── knowledge-management.spineworkspace.com → Knowledge Management\n├── support.spineworkspace.com      → Support Workbench\n├── brandstore.spineworkspace.com   → BrandStore (internal)\n└── book-of-records.spineworkspace.com → Org Memory (internal)\n```\n\n## Common Sidebar Structure (IW Grammar)\n\nAll domain workspaces share a common sidebar grammar. Only the **Work** section is projection-aware.\n\n### Home\n\n- Personal operational dashboard\n- Cross-domain aggregation\n- Workspace awareness\n- Recent activity\n- Priority ranking\n- Personal KPIs\n- Pending approvals\n- AI recommendations\n- Quick actions\n- Workspace continuity entry\n- Personal Twin context\n- Cross-projection navigation\n\n### My Work\n\n- Assigned work\n- Delegated work\n- Waiting on others\n- Waiting for me\n- Tasks\n- Goals\n- Deliverables\n- Follow-ups\n- Approvals\n- SLA commitments\n- Calendar-linked work\n- Twin-assisted execution\n\n### Inbox\n\n- Unified operational inbox\n- Aggregated from: Email, Chat, CRM, Tickets, Comments, Mentions, Notifications, AI-generated follow-ups, Connector events, Workflow events, Approval requests\n- With: Priority scoring, Deduplication, Threading, AI summaries, Suggested actions\n\n### Tasks\n\n- Universal task execution\n- Supports: Manual tasks, Workflow tasks, Agent-generated tasks, Connector-generated tasks, Scheduled tasks, Recurring tasks, Approvals, Dependencies, SLA tracking, Context-aware execution\n\n### My Queue\n\n- Dynamic execution queue\n- Generated using: Priority engine, OODA, Signals, Deadlines, Dependencies, AI prioritization, Role, Current context, Business impact, Attention management\n\n### Approvals\n\n- Human-in-the-loop governance\n- Supports: Publishing, Budget approval, Connector approval, AI approval, Write-back approval, Customer approval, Deployment approval, Security approval, Policy approval, Escalation workflows, Full audit trail\n\n### Notifications\n\n- Workspace event stream\n- Sources: Connectors, Pipelines, Agents, Skills, Workflows, Governance, Security, Platform, Workspace, Twin, Human collaboration\n- With intelligent grouping and prioritization\n\n### Recent Work\n\n- Continuity surface\n- Shows: Recently viewed entities, Recently edited records, Recent conversations, Recent workflows, Recent approvals, Recent Twin sessions, Recent canvas work, Recent documents, Recent context, Resume previous work\n\n### Favorites\n\n- Pinned operational assets\n- Includes: Views, Dashboards, Accounts, Campaigns, Customers, Reports, Skills, Agents, Workflows, Documents, Canvases, Pipelines\n\n### Communications\n\n- Unified communication layer\n\n### Activity Feed\n\n- Operational timeline\n- Combines: CRM activity, Emails, Meetings, Chats, Deployments, Customer interactions, Agent activity, Workflow execution, Connector events, Platform events\n- Mapped into one chronological Spine timeline\n\n### Email\n\n- Unified email workspace\n- Provides: Multi-provider inbox, AI summaries, Draft generation, Smart replies, CRM linking, Entity linking, Twin memory, Knowledge retrieval, Workflow initiation, Context gathering\n\n### Calendar\n\n- Unified scheduling\n- Supports: Multiple providers, Availability, AI scheduling, Meeting preparation, Agenda generation, Follow-up generation, Linked entities, Linked workflows, Context retrieval\n\n### Meetings\n\n- Meeting operating system\n- Includes: Preparation, Briefing, Live assistance, Recording, Transcript, Action extraction, Decisions, Follow-ups, Memory promotion, Workflow creation\n\n### Chat\n\n- Unified conversation layer\n- Across: Slack, Teams, Discord, Internal chat, MCP messaging, AI conversations\n- With: Context retrieval, Entity linking, Workspace memory, Suggested actions\n\n### Calls\n\n- Voice communication\n- Supports: Call preparation, Live notes, Transcript, CRM linking, Entity extraction, Tasks, Decisions, Follow-ups, Memory updates\n\n### Documents Shared\n\n- Collaborative document workspace\n- Supports: Google Docs, Office, Notion, Coda, PDFs, Internal documents\n- With: Semantic indexing, Context retrieval, Version awareness, AI understanding, Knowledge promotion\n\n### Personal\n\n- Personal knowledge and thinking space\n\n### Notes\n\n- Personal operational memory\n- Supports: Quick capture, Linked entities, AI organization, Tags, Knowledge promotion, Twin context, Search, Continuity\n\n### Knowledge Base\n\n- Workspace knowledge graph\n- Provides: Canonical knowledge, Policies, Documentation, Procedures, Product knowledge, Customer knowledge, Organizational knowledge, Semantic search, RAG context, Source traceability\n\n### Brainstorming Sessions\n\n- Collaborative ideation\n- Supports: Whiteboards, Structured thinking, AI ideation, Twin collaboration, Decision capture, Research, Concept evolution, Memory promotion\n\n### Activity\n\n- Personal operational timeline\n- Tracks: Work history, AI activity, Decisions, Context switches, Workflow participation, Learning, Memory evolution, Workspace interactions\n\n## Work Section\n\nRoute based on: Role × Department × Industry × Workspace policy\n\nBuilt from:\n\n- Spine projections\n- Views (table, dashboard, board, canvas, feed, calendar)\n- Canvas\n- Tool capabilities\n- Twin execution through OODA\n- Skills\n- Agents\n- Workflows\n- Pipelines\n- Backend/frontend mappings\n- Operational databases\n- Context gathering\n- Entity360\n- Continuity memory\n\nEach projection should contain enough operational depth for a user to perform their complete job in the agentic era.\n\n## Platform Section\n\nShared platform capability layer provided by `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 (Organizations, Users, Roles, Permissions, Audit, Billing, Deployments, API Keys, Security, Admin, Paywall)\n\n## `apps/` — 11 entries\n\n```text\napps/\n│\n├── marketing/\n│   → Public Marketing application\n│   → www.spineworkspace.com\n│   → canonical public URLs\n│   → /solutions/* remains URL-stable\n│\n├── web/\n│   → Authenticated multi-domain User Workbench\n│   → *.spineworkspace.com\n│   → Common IW shell\n│   → Domain Workbenches\n│   → Role × Department × Industry × Context projections\n│\n├── one-access/\n│   → OneAuth\n│   → auth.spineworkspace.com\n│   → Identity\n│   → SSO\n│   → tenant/workspace resolution\n│   → onboarding\n│   → activation entry\n│\n├── activation/\n│   → Onboarding flow\n│   → activation.spineworkspace.com\n│\n├── auth/\n│   → Auth management UI\n│   → auth.spineworkspace.com\n│\n├── connector/\n│   → Connector management UI\n│   → connector.spineworkspace.com\n│\n├── platform/\n│   → Platform Control Surface\n│   → platform.spineworkspace.com\n│   → Integration Manager\n│   → Activation\n│   → Capabilities\n│   → MCP\n│   → AI\n│   → Memory\n│   → Pipelines\n│   → Governance\n│   → Observability\n│   → Administration\n│\n├── docs/\n│   → Public/developer documentation portal\n│\n├── mobile/\n│   → Mobile Workbench client\n│\n├── desktop/\n│   → Desktop Workbench client\n│\n├── mcp-servers/\n│   → Managed MCP server runtimes\n│\n└── portfolio/\n    → Deprecated / Absorbed into apps/platform\n```\n\n## `packages/` boundary\n\nDomain definitions and reusable product semantics belong here rather than becoming more apps.\n\n```text\npackages/\n├── workbenches/\n│   ├── founder\n│   ├── sales\n│   ├── account-success (TAM)\n│   ├── technical-account-success\n│   ├── finance\n│   ├── ops\n│   ├── engineering\n│   ├── marketing\n│   ├── business-intelligence\n│   ├── campaigns\n│   ├── knowledge-management\n│   ├── support\n│   ├── brandstore (internal)\n│   └── book-of-records (internal)\n│\n├── projection-engine/\n├── context/\n├── capability/\n├── workbench-config/\n├── workbench-common/\n├── spine-schema/\n├── spine-entities/\n├── auth/\n├── intelligence/\n├── shell/\n├── ui/\n├── SDKs/\n└── retained MFEs where genuinely reusable\n```\n\n## `services/` boundary\n\n```text\nservices/\n├── gateway/\n├── context/\n├── projection/\n├── spine-sync/\n├── loader/\n├── normalizer/\n├── pipeline/\n├── capability/\n├── governance/\n├── orchestrator/\n├── connectors/\n├── reconciliation/\n├── knowledge/\n├── memory/\n├── intelligence/\n└── observability/\n```\n\n## Storage migration boundary\n\n```text\nsql-migrations/\n      ↓\nNEON (Canonical Spine, durable tenant truth, history, relationships, provenance, governance, durable memory)\n\nmigrations/\n      ↓\nD1 / KV / distributed runtime (Operational Spine, active working set, projection state, current context, runtime state)\n```\n\n## Marketplace versus MCP\n\n```text\nmarketplace/\n= what can be discovered / installed / activated\n\nmcp/\n= MCP protocol implementation and bridges\n\napps/mcp-servers/\n= managed MCP runtime deployments\n```\n\n## Final repository law\n\n```text\napps/         = experiences\npackages/     = reusable product/domain definitions\nservices/     = runtime implementations\ncontracts/    = cross-boundary canonical contracts\nconfigs/      = environment/infrastructure configuration\nmarketplace/  = discoverable/installable capability inventory\nmcp/          = MCP protocol infrastructure\ndocs/         = architecture and implementation authority\nmigrations/   = Operational Spine/runtime migrations\nsql-migrations/ = Canonical Spine/Neon migrations\ntools/        = generation and engineering tooling\n```\n\n## Related Documents\n\n- [`PLATFORM_CONTROL_SURFACE_MAPPING.md`](PLATFORM_CONTROL_SURFACE_MAPPING.md) — Platform frontend ↔ backend canonical mapping with 12 surfaces, service ownership, read/write paths, and governance gates.\n"}