{"slug":"business/REPOSITORY_EXCAVATION","title":"IntegrateWise Repository: Complete Excavation Report","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/REPOSITORY_EXCAVATION.mdx","bytes":19116,"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## 🔍 System Overview\n\n**Repository:** NirmalPrinceJ/integratewise-live  \n**Date:** December 2024  \n**Architecture:** Monorepo (turborepo) with 40+ services and 20+ packages  \n**Runtime:** 100% Cloudflare (Workers, Durable Objects, D1, KV, Queues)  \n\n---\n\n## 📊 Repository Structure\n\n```\nintegratewise-live/\n├── apps/                          # User-facing applications\n│   ├── web/                       # Main web application (React/Next)\n│   ├── desktop/                   # Electron desktop app\n│   ├── mobile/                    # Mobile application\n│   └── web.old/                   # Legacy web app\n│\n├── services/                      # 40+ Cloudflare Workers services\n│   ├── twin-orchestrator/         # Agent Lee (Twin Orchestrator) ⭐\n│   ├── iw-agent-runtime/          # Agent runtime (with Twin Agent)\n│   ├── intelligence/              # Specialized agents\n│   ├── pipeline/                  # Task orchestration\n│   ├── mcp-connector/             # MCP protocol server\n│   ├── continuity/                # Memory & state persistence\n│   ├── connector/                 # Integration connectors\n│   ├── gateway/                   # API gateway\n│   ├── knowledge/                 # Knowledge base system\n│   ├── hermes/                    # Event streaming\n│   ├── capability-resolver/       # Agent capability discovery\n│   ├── agent-registry/            # Agent registration\n│   └── 25+ more specialized services\n│\n├── packages/                      # 20+ shared libraries\n│   ├── adk/                       # Agent Development Kit ⭐\n│   ├── db/                        # Database schemas\n│   ├── lib/                       # Shared utilities\n│   ├── types/                     # Type definitions\n│   ├── hermes-spine-memory/       # Spine/Memory system\n│   ├── integratewise-mcp-tool-connector/ # MCP tools\n│   ├── config/                    # Configuration\n│   ├── rbac/                      # Role-based access control\n│   ├── tenancy/                   # Multi-tenancy\n│   └── 11+ more packages\n│\n├── docs/                          # Documentation\n│   ├── architecture/\n│   ├── internal/\n│   ├── operations/\n│   ├── tech/\n│   └── public/\n│\n├── infra/                         # Infrastructure code\n│   ├── cloudflare/                # Cloudflare config\n│   └── vercel/                    # Vercel config\n│\n└── tests/                         # 6 test suites\n    ├── e2e/\n    ├── functional/\n    ├── playwright/\n    ├── edge/\n    ├── doctrine/\n    └── thesis/\n```\n\n---\n\n## 🤖 AGENT LEE (THE TWIN)\n\n### Location: `services/iw-agent-runtime/src/twin-agent.ts`\n\n**What is Agent Lee?**\n\nAgent Lee is the **personal orchestrator and adaptive mind** for each IntegrateWise user. Not a replaceable chatbot—a persistent operational system that:\n\n1. **Synthesizes** context from Spine, Memory, and sessions\n2. **Reasons** about decisions and operational patterns\n3. **Proposes** structured recommendations with confidence scores\n4. **Learns** from outcomes and updates personal profile\n5. **Coaches** users through complex decisions\n\n### Twin System Prompt (Core Loop)\n\n```typescript\n// From line 19-43\nYou are the personal IntegrateWise Twin for the user — the adaptive personal mind, \norchestrator, and operator for this user's operational continuity system.\n\nCORE IDENTITY & SELF-REALISATION LOOP (run before every response):\n  1. Observe    → Retrieve context from Spine/Memory/Sessions\n  2. Reflect    → Synthesize patterns\n  3. Learn      → Update learned_profile\n  4. Propose    → Generate decision with confidence\n  5. Coach      → Explain & flag approval needs\n```\n\n### Twin State (Learned Profile)\n\n```typescript\n// From buildLearnedProfileBlock (line 63-80)\nlearned_profile: {\n  communication_style: \"concise, strategic\",\n  focus_priorities: [\"high-leverage decisions\", \"strategic planning\"],\n  recent_lessons: [\n    \"Accounts > 100K are qualified leads\",\n    \"CSM approval indicates good qualification\"\n  ],\n  success_patterns: [\n    \"High-value + CSM approval → pursue\",\n    \"Industry: Tech = 2x conversion\"\n  ],\n  risk_tolerance_signals: [\"Prefer data-driven decisions\"],\n  profile_version: number  // Increments on updates\n}\n```\n\n### Twin Capabilities\n\n```typescript\n// From line 1\n```\n\nAgent Lee is built on the `agents` library with:\n- **Capabilities:** orchestrate, reason, propose, learn, coach\n- **Voice Integration:** Cloudflare Workers AI (STT/TTS)\n- **Memory:** Durable Objects + D1 (persistent)\n- **State:** TenantBrainDO (per-tenant state machine)\n\n---\n\n## 🏗️ Twin Orchestrator Service\n\n### Location: `services/twin-orchestrator/src/`\n\n**Modules:**\n```\ntwin-orchestrator/\n├── index.ts           # Main orchestration entry point (15KB)\n├── context.ts         # Context assembly (4KB)\n├── reasoning.ts       # Reasoning logic (3KB)\n├── proposals.ts       # Proposal generation (2.5KB)\n├── coordination.ts    # Multi-agent coordination (2.5KB)\n├── state.ts           # State management (1.6KB)\n└── types.ts           # TypeScript types (1.6KB)\n```\n\n**Key Responsibilities:**\n1. Coordinate work across specialized agents\n2. Maintain persistent Twin state\n3. Manage learned profiles\n4. Route tasks to appropriate agents\n5. Aggregate results and propose decisions\n\n---\n\n## 📚 Agent Development Kit (ADK)\n\n### Location: `packages/adk/src/`\n\n**Purpose:** Framework for building and composing agents\n\n**Components:**\n```typescript\n// agent-registry.ts - Register agents with capabilities\ninterface AgentCapability {\n  name: string;\n  description: string;\n  inputSchema: JSONSchema;\n  outputSchema: JSONSchema;\n}\n\n// registry.ts - Query agents by capability\nqueryAgentsByCapability(capability: string): Agent[]\n\n// resolver.ts - Resolve which agent should handle a task\ngetAgentForTask(task: Task): Agent\n\n// spine-cache.ts - Cache agent discovery results\n// types.ts - Shared TypeScript interfaces\n```\n\n---\n\n## 🧠 Ecosystem (Twin Runtime)\n\n### Location: `services/iw-agent-runtime/src/ecosystem/`\n\n**Files:**\n```\necosystem/\n├── continuity.ts          # Continuity context assembly\n├── memory-pipeline.ts     # Shared memory system\n├── index.ts               # Ecosystem exports\n└── (more specialized modules)\n```\n\n### Memory Pipeline\n\n```typescript\n// Shared, cross-agent memory with decay\nsaveMemory(content: string, scope: 'global' | 'tenant' | 'user')\nqueryMemory(filters: {tags, scope}, limit: number)\n// Decay: score *= exp(-age_days / 7)\n// Promotion: access_count boosting\n```\n\n### Continuity Context\n\n```typescript\n// Assembly of context for Twin decisions\nassembleContinuity(tenantId: string, userId: string): {\n  spine_data: {},        // Facts from Spine\n  shared_memory: [],     // Global learnings\n  session_history: [],   // Recent interactions\n  learned_profile: {}    // Twin's evolution\n}\n```\n\n---\n\n## 🗄️ Tenant Brain Durable Object\n\n### Location: `services/iw-agent-runtime/src/tenant-brain-do.ts`\n\n**What:** Per-tenant persistent state machine (Cloudflare Durable Object)\n\n**Stores:**\n```typescript\n{\n  tenant_id: string;\n  learned_profile: {\n    recent_lessons: string[];\n    success_patterns: string[];\n    risk_tolerance_signals: string[];\n  };\n  session_state: {\n    current_context: {};\n    active_proposals: [];\n    pending_approvals: [];\n  };\n  signal_queue: [];  // Governance signals\n  last_updated: Date;\n}\n```\n\n**Lifecycle:**\n1. Twin detects change\n2. Emits signal via `emitTriageInput`\n3. Signal goes through governance pipeline\n4. State updated in Durable Object\n5. Learned profile evolves\n\n---\n\n## 🔌 Key Service Integrations\n\n### MCP Connector\n**Location:** `services/mcp-connector/src/`\n\nExposes Agent Lee's capabilities as MCP tools:\n- `agent.orchestrate` - Coordinate multi-agent workflows\n- `agent.reason` - Synthesize decisions\n- `agent.propose` - Generate recommendations\n- `agent.learn` - Update from outcomes\n- `agent.coach` - Explain decisions\n\n### Pipeline Service\n**Location:** `services/pipeline/src/`\n\nRoutes work to specialized agents:\n1. Task submitted\n2. Registry queries for matching agent\n3. Agent executes\n4. Result captured in Spine\n5. Memory updated\n6. Twin learns\n\n### Intelligence Service\n**Location:** `services/intelligence/src/`\n\nSpecialized agents:\n- Lead Scoring Agent\n- Qualification Agent\n- Analytics Agent\n- Triage Agent\n- Forecasting Agent\n\n### Hermes (Event Streaming)\n**Location:** `services/hermes/src/`\n\nEvent bus for agent communication:\n- Agent discovery events\n- Proposal events\n- Learning signals\n- State changes\n\n---\n\n## 📡 Spine (Canonical Truth)\n\n### What is Spine?\n\nCentral event log + database:\n```\nSpine = D1 Database + Event Stream\n```\n\n**Stores:**\n- Events (all agent actions)\n- Decisions (with reasoning)\n- Outcomes (results of decisions)\n- Relationships (entity links)\n- Audit trail (immutable history)\n\n**Spine Query Language:**\n```typescript\n// Example from Twin\nconst leadData = await spineQuery(db, 'lead', '123');\nconst relatedDecisions = await spineQuery(db, 'decision', {\n  entity_id: '123',\n  type: 'qualification'\n});\n```\n\n---\n\n## 🔄 Data Flow: User Query → Twin Response\n\n```\nUser: \"Should we pursue lead #123?\"\n  ↓\n[1] Twin ACTIVATES\n    → evaluateActivation() checks eligibility\n    → Loads TenantBrainDO state\n  ↓\n[2] Twin OBSERVES (retrieveContext)\n    → Query Spine for lead data\n    → Query Memory for patterns\n    → Load learned_profile\n  ↓\n[3] Twin REFLECTS (reasoning.ts)\n    → Synthesize: lead + memory + profile\n    → Calculate confidence score\n  ↓\n[4] Twin COORDINATES (coordination.ts)\n    → Query registry for specialized agents\n    → Send requests to CSM Agent, Analytics Agent, etc.\n  ↓\n[5] Twin SYNTHESIZES RESULTS\n    → Combine responses into reasoning\n    → Apply learned patterns\n  ↓\n[6] Twin PROPOSES (proposals.ts)\n    → Generate recommendation with confidence\n    → Flag approval needs\n    → Create governance signal\n  ↓\n[7] Signal EMITTED (emitTriageInput)\n    → Signal → Governance Pipeline\n    → Update TenantBrainDO\n    → Spine records decision event\n  ↓\n[8] Memory UPDATES (memory-pipeline.ts)\n    → Save learning: \"Lead #123 qualified via CSM + value\"\n    → Add to global memory\n    → Update decay scores\n  ↓\n[9] Profile EVOLVES\n    → Add recent_lesson\n    → Update success_pattern\n    → Increment profile_version\n  ↓\nUser RECEIVES:\n  {\n    \"proposal\": \"PURSUE lead #123\",\n    \"confidence\": 0.88,\n    \"reasoning\": \"...\",\n    \"agents_consulted\": [...],\n    \"supporting_data\": {...},\n    \"next_step\": \"Awaiting your approval\"\n  }\n```\n\n---\n\n## 🛠️ Building Blocks\n\n### 1. Agents Library\n```typescript\n\n// Base class for all agents\nconst twinAgent = new Agent({\n  name: \"Lee Twin\",\n  model: \"claude-3.5-sonnet\",\n  instructions: buildTwinSystemPrompt(...)\n});\n\n// Voice capability\nconst VoiceTwin = withVoice(Agent);\n```\n\n### 2. Cloudflare Platform\n```typescript\n// D1 (Database)\nconst db = env.DB;  // SQL database binding\n\n// KV (Cache)\nconst cache = env.CACHE;  // Key-value store\n\n// Durable Objects (State)\nconst tenantBrain = env.TENANT_BRAIN_DO;  // State machine\n\n// Workers AI\nconst ai = new Ai(env.AI);  // LLM + voice models\n\n// Service Bindings\nconst mcp = env.MCP_CONNECTOR;  // Other workers\nconst pipeline = env.PIPELINE;\nconst continuity = env.CONTINUITY;\n```\n\n### 3. Capability Contract\n**Location:** `services/iw-agent-runtime/src/capability-contract.ts`\n\nDefines what Twin can do:\n```typescript\nconst CAPABILITY_CONTRACT = {\n  orchestrate: {\n    input: { task: string, context: object },\n    output: { agent_id: string, result: object }\n  },\n  reason: {\n    input: { facts: [], patterns: [] },\n    output: { synthesis: string, confidence: number }\n  },\n  propose: {\n    input: { synthesis: string },\n    output: { recommendation: string, confidence: number, approval_needed: boolean }\n  },\n  learn: {\n    input: { outcome: object },\n    output: { lessons_updated: number, profile_version: number }\n  }\n};\n```\n\n---\n\n## 📦 Key Packages\n\n### `packages/hermes-spine-memory/`\nSpine + Memory system\n\n### `packages/integratewise-mcp-tool-connector/`\nMCP tool integration\n\n### `packages/types/`\nShared TypeScript interfaces\n\n### `packages/config/`\nEnvironment configuration\n\n### `packages/db/`\nDatabase schema + migrations\n\n---\n\n## 🚀 Deployment Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│      Cloudflare Global Edge Network              │\n├─────────────────────────────────────────────────┤\n│                                                 │\n│  Workers (iw-agent-runtime, twin-orchestrator) │\n│  ├─ Twin Agent (Lee)                           │\n│  ├─ Specialized Agents                         │\n│  └─ MCP Server                                  │\n│           ↓↓↓                                    │\n│  ┌─────────────────────────────────┐           │\n│  │  Durable Objects                │           │\n│  │  ├─ TenantBrainDO (state)       │           │\n│  │  ├─ SharedMemoryDO (memory)     │           │\n│  │  └─ PipelineCoordinatorDO       │           │\n│  └─────────────────────────────────┘           │\n│           ↓↓↓                                    │\n│  ┌─────────────────────────────────┐           │\n│  │  D1 (PostgreSQL)                │           │\n│  │  ├─ Spine (events)              │           │\n│  │  ├─ agent_registry              │           │\n│  │  ├─ communication_log           │           │\n│  │  └─ tenant_state                │           │\n│  └─────────────────────────────────┘           │\n│           ↓↓↓                                    │\n│  ┌─────────────────────────────────┐           │\n│  │  KV Namespace                   │           │\n│  │  ├─ agent_msg:*                 │           │\n│  │  ├─ tool_registry:*             │           │\n│  │  └─ cache:*                     │           │\n│  └─────────────────────────────────┘           │\n│           ↓↓↓                                    │\n│  ┌─────────────────────────────────┐           │\n│  │  Queues                         │           │\n│  │  ├─ agent_tasks                 │           │\n│  │  ├─ signals                     │           │\n│  │  └─ proposals                   │           │\n│  └─────────────────────────────────┘           │\n│                                                 │\n└─────────────────────────────────────────────────┘\n```\n\n---\n\n## 📊 Services Summary\n\n| Service | Purpose | Tech |\n|---------|---------|------|\n| **twin-orchestrator** | Agent coordination | CF Worker |\n| **iw-agent-runtime** | Twin Agent runtime | CF Worker + VO |\n| **mcp-connector** | MCP protocol | CF Worker |\n| **pipeline** | Task routing | CF Worker |\n| **intelligence** | Specialized agents | CF Worker |\n| **continuity** | Memory persistence | CF Worker + VO |\n| **connector** | Integration connectors | CF Worker |\n| **gateway** | API gateway | CF Worker |\n| **knowledge** | Knowledge base | CF Worker |\n| **hermes** | Event streaming | CF Worker |\n| **capability-resolver** | Agent capability discovery | CF Worker |\n| **agent-registry** | Agent registration | CF Worker + D1 |\n\n---\n\n## 🎓 Learning Path\n\n### Level 1: Understanding Twin Architecture (1 hour)\n1. Read `twin-agent.ts` (system prompt + core loop)\n2. Review `twin-orchestrator/index.ts` (coordination logic)\n3. Understand `TenantBrainDO` (persistent state)\n\n### Level 2: Agent Communication (2 hours)\n1. Read `packages/adk/` (agent capabilities)\n2. Study `services/mcp-connector/` (MCP protocol)\n3. Understand inter-agent messaging\n\n### Level 3: Memory & Learning (2 hours)\n1. Review `memory-pipeline.ts` (decay algorithm)\n2. Study `continuity/` (context assembly)\n3. Understand learned profile evolution\n\n### Level 4: Full System (4+ hours)\n1. Trace full data flow (user query → Twin response)\n2. Study all 40 services\n3. Understand Cloudflare platform integration\n\n---\n\n## 🔗 Key Files to Review\n\n| File | Purpose | Lines |\n|------|---------|-------|\n| `services/iw-agent-runtime/src/twin-agent.ts` | Twin Agent core | 600+ |\n| `services/twin-orchestrator/src/index.ts` | Orchestration | 400+ |\n| `services/iw-agent-runtime/src/tenant-brain-do.ts` | State management | 300+ |\n| `packages/adk/src/registry.ts` | Agent registry | 200+ |\n| `services/mcp-connector/src/mcp-server.ts` | MCP server | 300+ |\n| `services/iw-agent-runtime/src/ecosystem/memory-pipeline.ts` | Memory system | 200+ |\n\n---\n\n## ✨ System Highlights\n\n1. **100% Cloudflare** - No external infrastructure needed\n2. **Persistent Twin** - State machine per tenant\n3. **Learned Profile** - Twin evolves from interactions\n4. **Multi-Agent Network** - Specialized agents coordinate\n5. **Governance Pipeline** - All decisions tracked\n6. **Complete Audit Trail** - Spine records everything\n7. **MCP Protocol** - External integration via standard protocol\n8. **Voice-Enabled** - Cloudflare Workers AI integration\n\n---\n\n## 🚀 Next Steps\n\n1. **Understand Twin** - Read `twin-agent.ts` system prompt\n2. **Study Orchestration** - Review `twin-orchestrator/` logic\n3. **Learn Memory** - Study decay + promotion algorithm\n4. **Explore Agents** - Review ADK and agent capabilities\n5. **Map Services** - Understand 40-service architecture\n6. **Deploy** - Use provided deployment scripts\n\n---\n\n**Status:** Full system mapped and documented.\n\n"}