# CxIDE — Architecture

## Overview

CxIDE is a native macOS SwiftUI code editor with an embedded C++ static analysis engine
and an in-process MCP (Model Context Protocol) agent providing 56 AI-assisted coding tools.

```
┌──────────────────────────────────────────────────────────────┐
│                    SwiftIDEApp.swift                          │
│                    (@main entry point)                        │
└──────────────────────┬───────────────────────────────────────┘
                       │
              ┌────────▼────────┐
              │ IDEContainerView │
              │  (root layout)   │
              └───┬──────────┬──┘
                  │          │
     ┌────────────▼──┐   ┌──▼───────────────┐
     │  Activity Bar  │   │   VSplitView      │
     │  + Sidebar     │   │  ┌─────────────┐  │
     │                │   │  │ CodeEditor   │  │
     │  • Explorer    │   │  │ + Minimap    │  │
     │  • Search      │   │  ├─────────────┤  │
     │  • Snippets    │   │  │ ConsoleView  │  │
     │  • Debug       │   │  │ (5 panels)   │  │
     │  • Agent       │   │  └─────────────┘  │
     │  • Settings    │   └───────────────────┘
     └───────────────┘
```

## Layers

### Presentation (Views/)

| File | Purpose |
| ---- | ------- |
| `IDEContainerView.swift` | Root layout: toolbar, activity bar, sidebar, editor, console, status bar |
| `CodeEditorView.swift` | Syntax-highlighted text editor with line numbers and breakpoints |
| `ConsoleView.swift` | Bottom panel: Console, Problems, Output, Debug, Agent chat |
| `AgentSidebarView.swift` | Agent sidebar: status, quick actions, tool browser |

### State (ViewModels/)

| File | Purpose |
| ---- | ------- |
| `EditorViewModel.swift` | Central app state: tabs, content, console, diagnostics, agent integration |

### Domain (Models/)

| File | Purpose |
| ---- | ------- |
| `Models.swift` | Diagnostic, ConsoleEntry, ActivityPanel, BottomPanel, AgentMessage, AgentStatus, AgentToolInfo |
| `CodeEngine.swift` (Models/) | CodeEngine protocol, FileItem |

### Services (Services/)

| File | Purpose |
| ---- | ------- |
| `AgentService.swift` | Agent orchestration: wraps MCPServer, routes messages, manages tool calls |

### C++ Engine (Core/)

| File | Purpose |
| ---- | ------- |
| `CodeEngine.hpp` | C++ header: EngineConfig, Token, SymbolInfo, AnalysisReport |
| `CodeEngine.cpp` | Swift tokenizer, symbol extraction, complexity metrics, issue detection |
| `SwiftEngineWrapper.h` | Objective-C interface (40+ methods) |
| `SwiftEngineWrapper.mm` | ObjC++ bridge implementation |
| `CodeEngine.swift` | CppEngineController (Swift facade), SwiftRuntimeEngine |

### MCP Agent (Agent/)

| File | Purpose |
| ---- | ------- |
| `MCPServer.swift` | MCP 2025-03-26 server: JSON-RPC 2.0, tool/resource/prompt registration |
| `MCPTypes.swift` | Protocol types: JsonRpcRequest, MCPToolDefinition, AnyCodable |
| `AgentConfig.swift` | Configuration: paths, exclusions, profiles, security |
| `AgentMemory.swift` | Session memory: file accesses, decisions, tasks, symbols |

### Agent Tools (Agent/Tools/)

| Module | Tools | Description |
| ------ | ----- | ----------- |
| `FileOpsTools.swift` | 10 | read, write, patch, search, list, tree, info, delete, move, find |
| `CodeIntelTools.swift` | 10 | complete, explain, review, refactor, fix, document, test, security, symbols, diff_explain |
| `GitTools.swift` | 8 | status, diff, log, commit, branch, blame, stash, show |
| `ProjectTools.swift` | 5 | detect, run, deps, config, create |
| `TerminalTools.swift` | 2 | exec, env |
| `XcodeTools.swift` | 10 | build, test, analyze, schemes, devices, swift_check, clean, archive, provisioning, swift_format |
| `DiagnosticsTools.swift` | 5 | workspace, lint, todo, duplicates, complexity |
| `AutoPilotTools.swift` | 6 | plan, execute, memory, context, diff, status |

### Engine Layer (Root)

| File | Purpose |
| ---- | ------- |
| `SwiftIDEApp.swift` | @main entry, WindowGroup, keyboard shortcuts |
| `EngineFactory.swift` | Factory: SwiftCodeEngine (macOS) vs SandboxedSwiftEngine |
| `SwiftCodeEngine.swift` | Full Swift execution via `/usr/bin/swift` Process |
| `SandboxedSwiftEngine.swift` | Safe line-by-line Swift interpreter |

## Data Flow

```
User Input
    │
    ▼
EditorViewModel          ◄── Commands, keyboard shortcuts
    │
    ├──► SwiftCodeEngine  ── Run code via Process ──► Console output
    │
    ├──► CppEngineController ── C++ analysis ──► Diagnostics
    │         │
    │         └──► SwiftEngineWrapper (ObjC++) ──► CodeEngine (C++)
    │
    └──► AgentService ── JSON-RPC ──► MCPServer
              │
              └──► 56 Tools (file ops, git, code intel, Xcode, etc.)
```

## Agent Integration (In-Process)

The MCP agent runs in-process — no HTTP server needed:

```swift
// AgentService.swift
let server = MCPServer(config: agentConfig)
FileOpsTools.register(on: server, config: agentConfig, memory: memory)
// ... 7 more tool modules

// Tool call: build JSON-RPC request, call directly
let response = server.handleJsonRpc(requestData)
```

**Message routing:**
1. User types in Agent panel or triggers command
2. `AgentService.sendMessage()` detects intent via keyword matching
3. Routes to appropriate tool call (e.g., "list files" → `file_list`)
4. Tool result displayed as `AgentMessage` in the chat panel

**Sandbox mode:** When enabled, only read-only tools are permitted (30 of 56).

## Security

- Path traversal protection in AgentConfig (`resolvePath()`)
- Dangerous command blocking in terminal tools
- API key redaction in logs
- Sandbox mode restricts to read-only operations
- pre-commit hook scans for hardcoded secrets