# lucid-fabrics/iphone-control architecture

> Architecture diagram of the GitHub repository lucid-fabrics/iphone-control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucid-fabrics/iphone-control
- Repository: https://github.com/lucid-fabrics/iphone-control

## Overview

iphone-control provides two ways to operate an iPhone Mirroring window: terminal commands, optionally exposed as MCP tools, and a macOS companion chat that can use AI tool calls. The main loop is request → model response/tool call → input or screenshot action → result shown to the user. The README documents CLI capabilities not represented by a top-level CLI source file in this tree; edges for those capabilities are therefore documented relationships, not claims about their implementation. The sampled source supports the companion flow; some listed features have only tree or README evidence.

Main entry points: [`helpers/input-src/main.swift`](https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/input-src/main.swift) (Device commands), [`companion/iPhoneCompanion/Models/Conversation.swift`](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Models/Conversation.swift) (Conversation state), [`companion/iPhoneCompanion/Services/AIServiceFactory.swift`](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/AIServiceFactory.swift) (Service selection), [`companion/iPhoneCompanion/Views/ChatView.swift`](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Views/ChatView.swift) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terminal["Terminal control"]
  node_terminal_control["Device commands<br/>[main.swift]"]
  node_input_helpers["Input helpers"]
  node_window_helper["Window lookup"]
  node_ocr_helper["OCR scan<br/>[ocr-image.swift]"]
  node_event_log["Event logging<br/>[event-logger.swift]"]
  node_registry[("App registry")]
end

subgraph group_companion["Companion app"]
  node_app_delegate["App lifecycle<br/>[AppDelegate.swift]"]
  node_chat_view["Chat interface<br/>[ChatView.swift]"]
  node_settings["Provider settings<br/>[SettingsView.swift]"]
  node_input_controller["Input control"]
  node_script_runner["Script runner<br/>[ScriptRunner.swift]"]
end

subgraph group_ai["AI chat"]
  node_conversation["Conversation state<br/>[Conversation.swift]"]
  node_messages["Chat messages<br/>[ChatMessage.swift]"]
  node_orchestrator["Tool loop"]
  node_tool_executor["Tool execution<br/>[ToolExecutor.swift]"]
  node_service_factory["Service selection"]
  node_provider_services["AI providers"]
  node_model_fetcher["Model discovery<br/>[ModelFetcher.swift]"]
end

subgraph group_support["Integration and support"]
  node_mcp_server["MCP tools<br/>[index.ts]"]
  node_keychain[("API credentials")]
  node_oauth["Claude Code auth"]
end

node_agent(("AI agent"))
node_mirroring["iPhone Mirroring"]
node_mcp_client(("MCP client"))

node_agent -.->|"requests actions"| node_terminal_control
node_terminal_control -.->|"controls and captures"| node_mirroring
node_terminal_control -.->|"finds window"| node_window_helper
node_terminal_control -.->|"dispatches input"| node_input_helpers
node_terminal_control -.->|"scans apps"| node_ocr_helper
node_terminal_control -.->|"reads and updates"| node_registry
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"wraps commands"| node_terminal_control
node_app_delegate -->|"presents"| node_chat_view
node_chat_view -->|"submits messages"| node_conversation
node_chat_view -->|"opens settings"| node_settings
node_conversation -->|"stores messages"| node_messages
node_conversation -->|"runs tool loop"| node_orchestrator
node_orchestrator -->|"executes tools"| node_tool_executor
node_tool_executor -->|"uses input control"| node_input_controller
node_tool_executor -->|"runs scripts"| node_script_runner
node_input_controller -->|"uses fallback"| node_script_runner
node_input_controller -.->|"posts input"| node_mirroring
node_conversation -->|"creates service"| node_service_factory
node_service_factory -->|"selects backend"| node_provider_services
node_provider_services -.->|"returns model output"| node_agent
node_service_factory -->|"loads API keys"| node_keychain
node_service_factory -->|"gets OAuth token"| node_oauth
node_settings -->|"fetches models"| node_model_fetcher
node_model_fetcher -.->|"checks catalogs"| node_provider_services
node_app_delegate -.->|"positions panel"| node_window_helper

click node_terminal_control "https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/input-src/main.swift"
click node_input_helpers "https://github.com/lucid-fabrics/iphone-control/tree/main/helpers/input-src"
click node_window_helper "https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/get-window-id.swift"
click node_ocr_helper "https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/ocr-image.swift"
click node_event_log "https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/event-logger.swift"
click node_mcp_server "https://github.com/lucid-fabrics/iphone-control/blob/main/mcp-server/src/index.ts"
click node_app_delegate "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/App/AppDelegate.swift"
click node_chat_view "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Views/ChatView.swift"
click node_settings "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Views/SettingsView.swift"
click node_conversation "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Models/Conversation.swift"
click node_messages "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Models/ChatMessage.swift"
click node_orchestrator "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ToolOrchestrator.swift"
click node_tool_executor "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ToolExecutor.swift"
click node_input_controller "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/InputController.swift"
click node_script_runner "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ScriptRunner.swift"
click node_service_factory "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/AIServiceFactory.swift"
click node_provider_services "https://github.com/lucid-fabrics/iphone-control/tree/main/companion/iPhoneCompanion/Services"
click node_model_fetcher "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ModelFetcher.swift"
click node_keychain "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Utilities/KeychainHelper.swift"
click node_oauth "https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Utilities/ClaudeCodeAuthHelper.swift"
click node_registry "https://github.com/lucid-fabrics/iphone-control/tree/main/helpers/input-src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_terminal_control,node_input_helpers,node_window_helper,node_ocr_helper,node_event_log,node_registry,node_mcp_client toneBlue
class node_app_delegate,node_chat_view,node_settings,node_input_controller,node_script_runner toneAmber
class node_conversation,node_messages,node_orchestrator,node_tool_executor,node_service_factory,node_provider_services,node_model_fetcher toneMint
class node_mcp_server,node_keychain,node_oauth toneRose
class node_agent,node_mirroring toneIndigo
```

## Components

### Terminal control

- [Device commands](https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/input-src/main.swift): `helpers/input-src/main.swift`
- [Input helpers](https://github.com/lucid-fabrics/iphone-control/tree/main/helpers/input-src): `helpers/input-src`
- [Window lookup](https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/get-window-id.swift): `helpers/get-window-id.swift`
- [OCR scan](https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/ocr-image.swift): `helpers/ocr-image.swift`
- [Event logging](https://github.com/lucid-fabrics/iphone-control/blob/main/helpers/event-logger.swift): `helpers/event-logger.swift`
- [App registry](https://github.com/lucid-fabrics/iphone-control/tree/main/helpers/input-src): `helpers/input-src`

### Companion app

- [App lifecycle](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/App/AppDelegate.swift): `companion/iPhoneCompanion/App/AppDelegate.swift`
- [Chat interface](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Views/ChatView.swift): `companion/iPhoneCompanion/Views/ChatView.swift`
- [Provider settings](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Views/SettingsView.swift): `companion/iPhoneCompanion/Views/SettingsView.swift`
- [Input control](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/InputController.swift): `companion/iPhoneCompanion/Services/InputController.swift`
- [Script runner](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ScriptRunner.swift): `companion/iPhoneCompanion/Services/ScriptRunner.swift`

### AI chat

- [Conversation state](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Models/Conversation.swift): `companion/iPhoneCompanion/Models/Conversation.swift`
- [Chat messages](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Models/ChatMessage.swift): `companion/iPhoneCompanion/Models/ChatMessage.swift`
- [Tool loop](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ToolOrchestrator.swift): `companion/iPhoneCompanion/Services/ToolOrchestrator.swift`
- [Tool execution](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ToolExecutor.swift): `companion/iPhoneCompanion/Services/ToolExecutor.swift`
- [Service selection](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/AIServiceFactory.swift): `companion/iPhoneCompanion/Services/AIServiceFactory.swift`
- [AI providers](https://github.com/lucid-fabrics/iphone-control/tree/main/companion/iPhoneCompanion/Services): `companion/iPhoneCompanion/Services`
- [Model discovery](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Services/ModelFetcher.swift): `companion/iPhoneCompanion/Services/ModelFetcher.swift`

### Integration and support

- [MCP tools](https://github.com/lucid-fabrics/iphone-control/blob/main/mcp-server/src/index.ts): `mcp-server/src/index.ts`
- [API credentials](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Utilities/KeychainHelper.swift): `companion/iPhoneCompanion/Utilities/KeychainHelper.swift`
- [Claude Code auth](https://github.com/lucid-fabrics/iphone-control/blob/main/companion/iPhoneCompanion/Utilities/ClaudeCodeAuthHelper.swift): `companion/iPhoneCompanion/Utilities/ClaudeCodeAuthHelper.swift`

### Other components

- **AI agent**
- **iPhone Mirroring**
- **MCP client**

## Connections

- AI agent → Device commands: requests actions
- Device commands → iPhone Mirroring: controls and captures
- Device commands → Window lookup: finds window
- Device commands → Input helpers: dispatches input
- Device commands → OCR scan: scans apps
- Device commands → App registry: reads and updates
- MCP client → MCP tools: calls tools
- MCP tools → Device commands: wraps commands
- App lifecycle → Chat interface: presents (evidence: `companion/iPhoneCompanion/App/AppDelegate.swift`)
- Chat interface → Conversation state: submits messages (evidence: `companion/iPhoneCompanion/Views/ChatView.swift`)
- Chat interface → Provider settings: opens settings (evidence: `companion/iPhoneCompanion/Views/ChatView.swift`)
- Conversation state → Chat messages: stores messages (evidence: `companion/iPhoneCompanion/Models/Conversation.swift`)
- Conversation state → Tool loop: runs tool loop (evidence: `companion/iPhoneCompanion/Models/Conversation.swift`)
- Tool loop → Tool execution: executes tools (evidence: `companion/iPhoneCompanion/Services/ToolOrchestrator.swift`)
- Tool execution → Input control: uses input control (evidence: `companion/iPhoneCompanion/Services/ToolExecutor.swift`)
- Tool execution → Script runner: runs scripts (evidence: `companion/iPhoneCompanion/Services/ToolExecutor.swift`)
- Input control → Script runner: uses fallback (evidence: `companion/iPhoneCompanion/Services/InputController.swift`)
- Input control → iPhone Mirroring: posts input
- Conversation state → Service selection: creates service (evidence: `companion/iPhoneCompanion/Models/Conversation.swift`)
- Service selection → AI providers: selects backend (evidence: `companion/iPhoneCompanion/Services/AIServiceFactory.swift`)
- AI providers → AI agent: returns model output
- Service selection → API credentials: loads API keys (evidence: `companion/iPhoneCompanion/Services/AIServiceFactory.swift`)
- Service selection → Claude Code auth: gets OAuth token (evidence: `companion/iPhoneCompanion/Services/AIServiceFactory.swift`)
- Provider settings → Model discovery: fetches models (evidence: `companion/iPhoneCompanion/Views/SettingsView.swift`)
- Model discovery → AI providers: checks catalogs
- App lifecycle → Window lookup: positions panel (evidence: `companion/iPhoneCompanion/App/AppDelegate.swift`)
