{"slug":"documentation/MONOREPO_STRUCTURE_FINAL","title":"IntegrateWise: Monorepo Structure & 10% Implementation Roadmap","section":"documentation","sectionLabel":"Documentation","status":"unclassified","type":"document","path":"documentation/MONOREPO_STRUCTURE_FINAL.mdx","bytes":15610,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\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**Architecture:** Canonical Ecosystem v2.1\n**Structure:** Single monorepo with clear Consumer → Bridge → Kernel → Provider separation\n**Status:** Architecture locked, 58 TODOs mapped to structure\n\n---\n\n## Monorepo Shape (LOCKED)\n\n```\nintegratewise/\n  apps/                          # Thin consumer surfaces\n    marketing/                   # Marketing landing pages\n    workspace/                   # Main continuity interface\n    core-engine/                 # Core orchestration UI\n    ai-workspace/                # AI assistant workspace\n    admin/                        # Admin dashboard\n    mobile/                       # Mobile app shell\n  packages/                      # Shared contracts & SDK\n    ui/                          # Component library (shadcn)\n    auth/                         # Auth primitives\n    api-client/                   # Gateway SDK (✓ existing)\n    sdk/                          # TypeScript SDK\n    mcp/                          # MCP client & server\n    shared-types/                 # Type definitions\n    entities/                     # Entity schemas\n    schemas/                      # Validation schemas\n    hooks/                        # React hooks\n    config/                       # Configuration\n    utils/                        # Utilities\n    permissions/                  # Permission model\n    feature-flags/                # Feature flags\n  services/                      # Backend capabilities (behind bridge)\n    gateway/                      # Continuity Bridge implementation (✓ partial)\n    ingestion/                    # Signal ingestion & normalization\n    cognition/                    # Reasoning & intelligence\n    memory/                       # Memory engine\n    governance/                   # Policy & approval\n    connectors/                   # Provider integrations\n  infra/                         # Deployment & infrastructure\n    cloudflare/                   # Workers, KV, D1\n    ci-cd/                        # GitHub Actions workflows\n    terraform/                    # IaC\n    docker/                       # Container configs\n  docs/                          # Documentation (LOCKED)\n    ecosystem-thesis.md           # ✓ Ecosystem doctrine\n    canonical-architecture.md     # ✓ Architecture doctrine\n    contract-discovery.md         # TODO: Discovery schema\n    contract-capabilities.md      # TODO: Capability definitions\n    contract-events.md            # TODO: Event definitions\n    deployment.md                 # TODO: Deployment guide\n    sdk-guide.md                  # TODO: SDK usage guide\n    mcp-guide.md                  # TODO: MCP integration guide\n```\n\n---\n\n## 10% Implementation Roadmap (58 TODOs Mapped)\n\n### TIER 1: Critical (30-35 hours) - 12 TODOs\n\n#### services/gateway/ (11 TODOs) - Continuity Bridge Implementation\n\n**Authentication Layer (3 TODOs)**\n- Gateway auth: validate token against auth service\n- Gateway auth: call auth service for session\n- Gateway auth: fetch current user\n- Location: `services/gateway/src/middleware/auth.ts`\n- Pattern: Inject AuthServiceClient, call methods, compose context\n\n**Initialization Layer (3 TODOs)**\n- FacadeRegistry initialization: dependency injection setup\n- FacadeRegistry: apply caching for projections\n- FacadeRegistry: apply rate limiting\n- Location: `services/gateway/src/bootstrap/facade-registry.ts`\n- Pattern: Initialize singleton, register with DI container\n\n**Core Endpoints (5 TODOs)**\n- GET /entities/:id → Entity360 service (entity + relationships + signals + memory)\n- GET /search/entities → Entity search service\n- GET /memory → Query adaptive memory with decay/links/promotion\n- POST /memory → Save to adaptive memory with scoping\n- DELETE /memory/:id → Delete memory item\n- Location: `services/gateway/src/routes/core.ts`\n- Pattern: ServiceClient call, compose DTO, apply gating, return\n\n#### docs/ (1 TODO) - Discovery Contract Documentation\n\n- Create `docs/contract-discovery.md`: Discovery response schema & examples\n- Schema: identity info, capabilities, navigation, workbenches, projections, policies, features\n- Examples: role-based discovery, tier-based features, device-specific optimizations\n\n---\n\n### TIER 2: Complete Phase 2e (70-80 hours) - 28 TODOs\n\n#### services/gateway/ (21 TODOs)\n\n**Entity & Memory Operations (6 TODOs) - CONTINUED**\n- GET /memory/search → Semantic memory search\n- Query adaptive memory with decay/links/promotion (implementation detail)\n- Plus 4 more core endpoints already listed\n\n**Connector Management (4 TODOs)**\n- GET /connectors → Get all connectors + status\n- GET /connectors/:id/status → Get specific connector status\n- POST /connectors/:id/sync → Trigger connector sync via workflow\n- POST /connectors/:id/oauth → Exchange OAuth code for access\n- Location: `services/gateway/src/routes/connectors.ts`\n\n**Proposals & Governance (6 TODOs)**\n- POST /proposals → Create proposal, emit to governance\n- GET /proposals/:id → Get proposal\n- POST /proposals/:id/approve → Approve + execute if approved\n- POST /proposals/:id/reject → Reject proposal\n- GET /proposals → List proposals with filters\n- Location: `services/gateway/src/routes/governance.ts`\n\n**Capabilities & Execution (4 TODOs)**\n- GET /capabilities → List all available capabilities\n- GET /capabilities/:id/schema → Get capability schema\n- POST /capabilities/:id/execute → Queue capability execution\n- GET /capabilities/:id/execution/:execId → Get execution status\n- Location: `services/gateway/src/routes/capabilities.ts`\n\n**Insights, Tasks, Chat (5 TODOs)**\n- GET /insights → Get/generate insights\n- GET /insights/:id → Get specific insight\n- POST /tasks → Create task\n- GET /tasks/:id → Get task\n- POST /tasks/:id/complete → Complete task + emit memory\n- POST /chat/threads → Create thread\n- POST /chat/threads/:id/messages → Send message, get AI response\n- GET /chat/threads/:id/messages → Get chat history\n- DELETE /chat/threads/:id → Delete thread\n- Spine events (2 TODOs)\n- Location: `services/gateway/src/routes/experiences.ts`\n\n#### services/projection-engine/ (7 TODOs)\n\n**Remaining 7 Adapters** - Implement remaining facades following MorningContextFacade pattern\n\n1. **GovernanceBoardFacade** → Tasks + Proposals + Decisions\n2. **InboxFacade** → Signals + Proposals unified\n3. **AccountHealthFacade** → Spine + Signals + Timeline\n4. **RenewalForecastFacade** → Spine + Insights + Renewals\n5. **MCPConsoleFacade** → MCP registry + Schema\n6. **WorkflowEditorFacade** → Workflows + Templates\n7. **BrainstormWorkbenchFacade** → Memory + Entities + Chat\n\n- Location: `services/projection-engine/src/facades/adapters.ts`\n- Pattern: Inject ServiceClientFactory, call services, compose DTO, gating applied\n\n#### docs/ (2 TODOs)\n\n- `docs/contract-capabilities.md` → Define all 40+ capabilities with schemas\n- `docs/contract-events.md` → Define all event types (Signal, Proposal, Approval, Outcome, Notification, Stream)\n\n---\n\n### TIER 3: Enhancement (40-50 hours) - 18 TODOs\n\n#### services/admin/ (4 TODOs)\n\n- Query Cloudflare Analytics API for real data\n- Trigger wrangler deploy via CF API\n- Implement rollback via CF API\n- Mock data placeholder (wire real CF when ready)\n- Location: `services/admin/src/analytics.ts`\n\n#### services/cognition/ (4 TODOs)\n\n- Wire to MorningBriefWorkflow when ready\n- Replace AI Search with final implementation (PRIORITY 4)\n- Store brief in D1 or send to Knowledge service\n- Wire to SignalWorkflow (2 instances)\n- Location: `services/cognition/src/workflows/`\n\n#### services/twin-orchestrator/ (1 TODO)\n\n- Stream-based reasoning implementation\n- Location: `services/twin-orchestrator/src/streaming.ts`\n- Effort: 8 hours (complex streaming setup)\n\n#### services/workflow/ (1 TODO)\n\n- Workflow executor implementation\n- Location: `services/workflow/src/executor.ts`\n- Effort: 6 hours\n\n#### services/knowledge/ (2 TODOs)\n\n- List preservation in chunker (extractLists function)\n- Tenant-scoped consumer implementation\n- Location: `services/knowledge/src/chunking/chunker.ts`\n\n#### services/mcp-connector/ (2 TODOs)\n\n- Call pipeline service binding for vault reads\n- Complete Spine MCP server implementation\n- Location: `services/mcp-connector/src/spine-mcp-server.ts`\n\n#### services/normalizer/ & services/loader/ (2 TODOs)\n\n- Accelerator implementation (normalizer)\n- AIRelay schema consolidation (loader)\n- Location: `services/normalizer/src/` and `services/loader/src/`\n\n#### services/projection-engine/src/facades/ (2 TODOs)\n\n- Cache implementation in FacadeRegistry\n- Emit audit event on projection access\n- Location: `services/projection-engine/src/facades/facade-registry.ts`\n\n#### docs/ (3 TODOs)\n\n- `docs/deployment.md` → Deployment & rollout procedure\n- `docs/sdk-guide.md` → SDK usage patterns & examples\n- `docs/mcp-guide.md` → MCP integration guide\n\n---\n\n## Mapping 58 TODOs to Packages (Shared Code)\n\n### packages/api-client/ (✓ Already exists as gateway-sdk.ts)\n\n**Status:** Complete, production-ready\n- Entity360, Memory, Twin, Signals, Insights, Predictions, Handoff, Stream, MCP\n- Already implemented and matches branch version\n\n**TODO in this package:** 0\n\n### packages/shared-types/ (5 TODOs indirectly)\n\n**Definitions needed for Gateway endpoints:**\n- ProjectionType, ProjectionContext, ProjectionResponse\n- CapabilityDefinition, CapabilitySchema, CapabilityExecution\n- EventType, EventPayload\n- DiscoveryResponse, DiscoveryCapability\n- ApprovalWorkflow, ApprovalDecision, RiskLevel\n\n**Status:** Partially complete, documentation TODO\n\n### packages/schemas/ (3 TODOs indirectly)\n\n- Memory query schema (decay, links, promotion filters)\n- Connector sync trigger schema\n- Proposal creation/decision schema\n\n**Status:** Partially complete via existing validation\n\n### packages/permissions/ (1 TODO indirectly)\n\n- Governance policy evaluation rules\n- Role/tier capability access matrix\n\n**Status:** Implemented in ContextGatingEngine, needs documentation\n\n### packages/mcp/ (2 TODOs indirectly)\n\n- MCP server for Spine (mcp-connector related)\n- MCP routing in bridge\n\n**Status:** Partial, needs completion\n\n---\n\n## Mapping 58 TODOs to Apps (Consumer Surfaces)\n\n### apps/workspace/ (7 TODOs indirectly)\n\n**Uses:** Gateway SDK + Projections\n\n**TODOs:**\n- Connect Gateway SDK to all endpoints (automatic when gateway complete)\n- Implement UI for 7 remaining projections (GovernanceBoard, Inbox, AccountHealth, RenewalForecast, MCP, Workflow, Brainstorm)\n- Wire approval workflows UI to governance endpoints\n- Wire tasks UI to task endpoints\n- Wire chat UI to chat endpoints\n\n**Status:** UI components exist, needs wiring to new endpoints\n\n### apps/ai-workspace/ (1 TODO indirectly)\n\n**Uses:** Twin capabilities, streaming endpoints\n\n**TODO:**\n- Wire Twin interface to streaming response endpoints (when Twin executor complete)\n\n### apps/admin/ (4 TODOs directly)\n\n**TODOs:** Analytics queries (see services/admin above)\n\n### apps/mobile/ (1 TODO indirectly)\n\n**TODO:**\n- Device-aware optimization (already gated in context gating)\n\n---\n\n## Mapping 58 TODOs to Infrastructure\n\n### infra/cloudflare/ (1 TODO)\n\n**TODO:** Trigger deploy & rollback via CF API (in services/admin, wiring to infra)\n\n### infra/ci-cd/ (0 TODOs)\n\n**Status:** Complete, workflows exist\n\n### infra/terraform/ (0 TODOs)\n\n**Status:** Can reference kiro/continuity-bridge-v3.7 branch\n\n---\n\n## Summary by Component Type\n\n| Component | Type | TODOs | Status |\n|-----------|------|-------|--------|\n| **services/gateway/** | Bridge | 11 | Tier 1 - Critical |\n| **services/projection-engine/** | Bridge | 7 | Tier 2 - Adapters |\n| **services/cognition/** | Kernel | 4 | Tier 3 - Enhancement |\n| **services/governance/** | Kernel | 1 | Tier 2 - Already imported |\n| **services/twin-orchestrator/** | Kernel | 1 | Tier 3 - Complex |\n| **services/workflow/** | Kernel | 1 | Tier 3 - Complex |\n| **services/memory/** | Kernel | 0 | Complete |\n| **services/knowledge/** | Kernel | 2 | Tier 3 - Enhancement |\n| **services/mcp-connector/** | Bridge/Kernel | 2 | Tier 3 - Enhancement |\n| **services/normalizer/** | Kernel | 1 | Tier 3 - Enhancement |\n| **services/loader/** | Kernel | 1 | Tier 3 - Enhancement |\n| **services/admin/** | Kernel | 4 | Tier 3 - Enhancement |\n| **packages/api-client/** | SDK | 0 | Complete |\n| **packages/shared-types/** | SDK | 0 | Complete, docs TODO |\n| **packages/schemas/** | SDK | 0 | Complete |\n| **packages/permissions/** | SDK | 0 | Complete |\n| **packages/mcp/** | SDK | 0 | Complete, integration TODO |\n| **docs/** | Documentation | 5 | Tier 1-2 - Critical |\n| **infra/** | Infrastructure | 0 | Complete, reference available |\n| **apps/workspace/** | Consumer | 0 | Wiring automatic |\n| **apps/ai-workspace/** | Consumer | 0 | Wiring automatic |\n| **apps/admin/** | Consumer | 0 | Wiring automatic |\n| **TOTAL** | — | **58** | **Mapped & Sequenced** |\n\n---\n\n## Implementation Sequence by Component\n\n### Week 1-2: services/gateway/ (Tier 1)\n- Implement auth layer (3 TODOs)\n- Implement FacadeRegistry initialization (3 TODOs)\n- Implement core entity/memory endpoints (5 TODOs)\n- **Output:** All 31 gateway endpoints routable, APIs functional\n\n### Week 3: docs/ (Tier 1)\n- Create contract-discovery.md\n- **Output:** Discovery contract finalized\n\n### Week 4-6: services/projection-engine/ + services/gateway/ (Tier 2)\n- Wire 7 remaining adapters\n- Implement connector management (4 TODOs)\n- Implement proposals & governance (6 TODOs)\n- Implement capabilities & execution (4 TODOs)\n- Implement insights, tasks, chat (5 TODOs)\n- **Output:** Full feature coverage, all adapters operational\n\n### Week 7: docs/ (Tier 2)\n- Create contract-capabilities.md, contract-events.md\n\n### Week 8+: Tier 3 + Phase 3 + Quality\n\n---\n\n## Consumer Surface Dependencies\n\nOnce Tier 1 & 2 complete, each app can be wired:\n\n| App | Depends On | Endpoints Needed | Effort |\n|-----|-----------|------------------|--------|\n| **workspace/** | All | All 31 gateway | 1 week |\n| **ai-workspace/** | Twin, Stream | Twin executor | 3 days |\n| **admin/** | Analytics | Admin endpoints | 2 days |\n| **mobile/** | All (gated) | All 31 gateway | 3 days |\n| **core-engine/** | Orchestration | Capability execution | 1 week |\n\n---\n\n## Quality Gates for All TODOs\n\nEvery TODO must pass:\n- [ ] Service client wired\n- [ ] Error handling with graceful degradation\n- [ ] Promise.allSettled() or async/await\n- [ ] Composed into proper DTO\n- [ ] Gating applied (or explicitly bypassed)\n- [ ] Types complete (no `any`)\n- [ ] Per Ecosystem Thesis v2.1\n- [ ] Unit tested with mock clients\n- [ ] Integration tested with real clients\n\n---\n\n## Success Criteria\n\n**10% → 0% (Complete):**\n- [ ] All 58 TODOs implemented\n- [ ] All 31 gateway endpoints operational\n- [ ] All 7 remaining adapters wired\n- [ ] All 5 discovery/capability/event docs complete\n- [ ] All apps wired to bridge\n- [ ] Error resilience tested\n- [ ] Production ready for Phase 3\n- [ ] Single monorepo, no scattered repos\n- [ ] Consumer → Bridge → Kernel → Provider separation maintained\n- [ ] Doctrine (Thesis v2.1) reflected in all code\n\n---\n\n**Last Updated:** Monorepo structure locked to Canonical Ecosystem v2.1\n**Total Effort:** 140-165 hours (10 engineering weeks)\n**Structure:** Single monorepo, clear separation of concerns\n**Status:** Architecture complete, implementation path clear\n"}