{"slug":"strategy/product-strategy/CODEBASE_ALIGNMENT_SPEC","title":"Codebase Alignment Specification","section":"strategy","sectionLabel":"Strategy","status":"current","type":"document","path":"strategy/product-strategy/CODEBASE_ALIGNMENT_SPEC.mdx","bytes":12372,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status:** Active alignment plan  \n> **Date:** July 12, 2026  \n> **Authority:** Nirmal (Founder)  \n> **Canonical Reference:** [CANONICAL_PLATFORM_ARCHITECTURE.md](./CANONICAL_PLATFORM_ARCHITECTURE.md)  \n> **Purpose:** Maps current services to canonical Platform Planes and defines alignment actions\n\n---\n\n## Current State\n\nThe codebase has **30 services** in `services/`. The canonical architecture defines **18 Platform Planes**. There is a significant mismatch that needs resolution.\n\n---\n\n## Service → Plane Mapping\n\n### Direct Mappings (Service exists and maps to a Plane)\n\n| Current Service     | Canonical Plane                         | Wrangler Name               | Status                                   |\n| ------------------- | --------------------------------------- | --------------------------- | ---------------------------------------- |\n| `pipeline`          | **Pipeline**                            | integratewise-pipeline      | ✅ Maps                                  |\n| `connector`         | **Integration Manager** (API Connector) | connector                   | ✅ Maps                                  |\n| `mcp-connector`     | **Integration Manager** (MCP)           | integratewise-mcp-connector | ✅ Maps                                  |\n| `intelligence`      | **Integration Manager** (AI Connector)  | intelligence                | ✅ Maps                                  |\n| `knowledge`         | **Knowledge**                           | knowledge                   | ✅ Maps                                  |\n| `continuity`        | **Continuity Pipeline**                 | continuity                  | ✅ Maps                                  |\n| `hermes`            | **Hermes**                              | integratewise-hermes        | ✅ Maps                                  |\n| `govern`            | **Governance Engine**                   | integratewise-govern        | ✅ Maps                                  |\n| `store`             | **Adaptive Spine**                      | integratewise-store         | ⚠️ Partial (Spine only, not Cache/Blobs) |\n| `think`             | **Twin** (reasoning)                    | integratewise-think         | ⚠️ Partial                               |\n| `iw-agent-runtime`  | **Twin** (runtime)                      | iw-agent-runtime            | ⚠️ Partial                               |\n| `twin-orchestrator` | **Twin** (orchestration)                | twin-orchestrator           | ⚠️ Partial                               |\n\n### Services Requiring Renaming/Consolidation\n\n| Current Service   | Target Plane            | Action Required                                    |\n| ----------------- | ----------------------- | -------------------------------------------------- |\n| `loader`          | **Pipeline**            | Consolidate into `pipeline`                        |\n| `normalizer`      | **Pipeline**            | Consolidate into `pipeline`                        |\n| `act`             | **Hermes** (execution)  | Consolidate into `hermes` or rename to `execution` |\n| `connector-sync`  | **Sync Engine**         | Rename to `sync-engine`                            |\n| `webhook-ingress` | **Integration Manager** | Consolidate into `connector` or rename             |\n| `agent-registry`  | **Capability Fabric**   | Rename to `capability-fabric`                      |\n| `workflow`        | **Capability Fabric**   | Consolidate into `capability-fabric`               |\n\n### Services That Are Cross-Cutting Infrastructure\n\n| Current Service | Infrastructure Layer                | Action Required                         |\n| --------------- | ----------------------------------- | --------------------------------------- |\n| `gateway`       | Identity + Secrets, Queues + Events | Keep as-is (cross-cutting)              |\n| `admin`         | Admin + Operations                  | Keep as-is (cross-cutting)              |\n| `billing`       | Billing + Entitlements              | Keep as-is (cross-cutting)              |\n| `telemetry`     | Observability                       | Keep as-is (cross-cutting)              |\n| `tenants`       | Configuration Manager (partial)     | Keep or consolidate into config-manager |\n| `signals`       | Queues + Events                     | Keep or consolidate into events         |\n\n### Services That Are Legacy/Unknown\n\n| Current Service         | Assessment            | Action Required                                             |\n| ----------------------- | --------------------- | ----------------------------------------------------------- |\n| `l2`                    | Legacy overlay schema | Evaluate for retirement                                     |\n| `core-engine`           | Unknown purpose       | Evaluate for retirement or consolidation                    |\n| `folder-watcher`        | File monitoring       | Evaluate for consolidation into connector                   |\n| `huggingface-inference` | Model inference       | Evaluate for consolidation into intelligence                |\n| `schema-ai`             | Schema management     | Evaluate for consolidation into config-manager or knowledge |\n\n### Canonical Planes Missing Services\n\n| Canonical Plane           | Current Service                            | Action Required                                       |\n| ------------------------- | ------------------------------------------ | ----------------------------------------------------- |\n| **Configuration Manager** | `tenants` (partial), `schema-ai` (partial) | Create new `config-manager` service                   |\n| **Activation Bridge**     | None                                       | Create new `activation-bridge` service                |\n| **Spine Cache**           | None (part of `store`)                     | Extract from `store` or create new service            |\n| **Blobs**                 | None (part of `store`)                     | Extract from `store` or create new service            |\n| **User Workbench**        | `apps/live` (frontend)                     | Frontend only, no service needed                      |\n| **Twin Memory**           | None (part of `iw-agent-runtime`)          | Extract from `iw-agent-runtime` or create new service |\n| **Session Logs**          | None (part of `iw-agent-runtime`)          | Extract from `iw-agent-runtime` or create new service |\n| **Twin Audit Logs**       | None (part of `iw-agent-runtime`)          | Extract from `iw-agent-runtime` or create new service |\n| **Sync Engine**           | `connector-sync` (partial)                 | Rename and expand `connector-sync`                    |\n\n---\n\n## Target State\n\nAfter alignment, the services should map to:\n\n### Platform Plane Services (18)\n\n| Service               | Canonical Plane       | Wrangler Name                     |\n| --------------------- | --------------------- | --------------------------------- |\n| `config-manager`      | Configuration Manager | integratewise-config-manager      |\n| `integration-manager` | Integration Manager   | integratewise-integration-manager |\n| `activation-bridge`   | Activation Bridge     | integratewise-activation-bridge   |\n| `pipeline`            | Pipeline              | integratewise-pipeline            |\n| `spine`               | Adaptive Spine        | integratewise-spine               |\n| `spine-cache`         | Spine Cache           | integratewise-spine-cache         |\n| `knowledge`           | Knowledge             | integratewise-knowledge           |\n| `blobs`               | Blobs                 | integratewise-blobs               |\n| `twin`                | Twin                  | integratewise-twin                |\n| `twin-memory`         | Twin Memory           | integratewise-twin-memory         |\n| `session-logs`        | Session Logs          | integratewise-session-logs        |\n| `twin-audit-logs`     | Twin Audit Logs       | integratewise-twin-audit-logs     |\n| `capability-fabric`   | Capability Fabric     | integratewise-capability-fabric   |\n| `governance-engine`   | Governance Engine     | integratewise-governance-engine   |\n| `hermes`              | Hermes                | integratewise-hermes              |\n| `sync-engine`         | Sync Engine           | integratewise-sync-engine         |\n| `continuity-pipeline` | Continuity Pipeline   | integratewise-continuity-pipeline |\n\n### Cross-Cutting Infrastructure Services (8)\n\n| Service      | Infrastructure Layer                | Wrangler Name            |\n| ------------ | ----------------------------------- | ------------------------ |\n| `gateway`    | Identity + Secrets, Queues + Events | gateway                  |\n| `admin`      | Admin + Operations                  | integratewise-admin      |\n| `billing`    | Billing + Entitlements              | integratewise-billing    |\n| `telemetry`  | Observability                       | integratewise-telemetry  |\n| `tenants`    | Config State                        | integratewise-tenants    |\n| `events`     | Queues + Events                     | integratewise-events     |\n| `secrets`    | Identity + Secrets                  | integratewise-secrets    |\n| `deployment` | Deployment + Runtime                | integratewise-deployment |\n\n### Frontend Apps (unchanged)\n\n| App              | Purpose                  |\n| ---------------- | ------------------------ |\n| `apps/live`      | User Workbench (primary) |\n| `apps/web`       | Legacy/marketing         |\n| `apps/mobile`    | Mobile app               |\n| `apps/desktop`   | Desktop app              |\n| `apps/workspace` | Internal workspace       |\n| `apps/docs`      | Documentation            |\n\n---\n\n## Alignment Actions\n\n### Phase 1: Consolidation (Reduce service count)\n\n1. **Consolidate Pipeline services:** Merge `loader` + `normalizer` into `pipeline`\n2. **Consolidate Twin services:** Merge `think` + `iw-agent-runtime` + `twin-orchestrator` into `twin`\n3. **Consolidate Capability Fabric:** Merge `agent-registry` + `workflow` into `capability-fabric`\n4. **Rename Sync Engine:** Rename `connector-sync` to `sync-engine`\n\n### Phase 2: Creation (Fill gaps)\n\n1. **Create `config-manager`** from `tenants` + `schema-ai`\n2. **Create `activation-bridge`** (new service)\n3. **Extract `spine-cache`** from `store`\n4. **Extract `blobs`** from `store`\n5. **Extract `twin-memory`** from `iw-agent-runtime`\n6. **Extract `session-logs`** from `iw-agent-runtime`\n7. **Extract `twin-audit-logs`** from `iw-agent-runtime`\n\n### Phase 3: Retirement (Remove legacy)\n\n1. **Evaluate `l2`** for retirement\n2. **Evaluate `core-engine`** for retirement or consolidation\n3. **Evaluate `folder-watcher`** for consolidation into connector\n4. **Evaluate `huggingface-inference`** for consolidation into intelligence\n5. **Evaluate `webhook-ingress`** for consolidation into connector\n\n### Phase 4: Rename (Align names)\n\n1. **Rename `store`** to `spine`\n2. **Rename `connector`** to `integration-manager`\n3. **Rename `mcp-connector`** (part of integration-manager)\n4. **Rename `intelligence`** to `ai-connector`\n5. **Rename `govern`** to `governance-engine`\n\n---\n\n## Priority Order\n\n1. **P0:** Consolidate Pipeline (loader + normalizer → pipeline)\n2. **P0:** Consolidate Twin (think + iw-agent-runtime + twin-orchestrator → twin)\n3. **P0:** Rename store → spine\n4. **P1:** Create config-manager from tenants + schema-ai\n5. **P1:** Create activation-bridge (new)\n6. **P1:** Rename connector-sync → sync-engine\n7. **P2:** Extract spine-cache, blobs from store\n8. **P2:** Extract twin-memory, session-logs, twin-audit-logs from iw-agent-runtime\n9. **P2:** Consolidate capability-fabric from agent-registry + workflow\n10. **P3:** Evaluate and retire legacy services\n\n---\n\n## Verification Criteria\n\nAfter alignment, verify:\n\n1. Every canonical Plane has a corresponding service\n2. No service exists without a canonical Plane mapping\n3. All wrangler.toml names follow the pattern `integratewise-{plane-name}`\n4. All services have consistent TypeScript types matching the canonical data models\n5. All services have consistent API contracts matching the canonical execution sequences\n6. Frontend components reference the correct service names\n7. Deploy scripts reference the correct service names\n8. Documentation references the correct service names\n"}