# ryancardin15/cinderdeck architecture

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

- Interactive diagram: https://gitdiagram.com/ryancardin15/cinderdeck
- Repository: https://github.com/ryancardin15/cinderdeck

## Overview

Cinderdeck is a native macOS development control deck: users define workspaces containing long-running services, one-shot tasks, and workflows, then start and inspect them locally or through agent controls. The README also documents recordings correlated with workspace logs, GitHub pull-request tools, capture and editing, and local history. The tree supports mapping these capabilities to their feature areas, but most workspace orchestration internals are unsampled; their links below rely on README statements rather than inspected call sites.

Main entry points: [`Cinderdeck/Features/Stacks/StacksViewModel.swift`](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StacksViewModel.swift) (Workspace state), [`Cinderdeck/Services/Capture/ScreenCaptureManager.swift`](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Capture/ScreenCaptureManager.swift) (Screen capture), [`Cinderdeck/App/AppStatusBarController.swift`](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/App/AppStatusBarController.swift) (Menu bar app), [`Cinderdeck/Features/Stacks/StacksTabView.swift`](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StacksTabView.swift) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_shell["Menu bar app"]
end

subgraph group_workspace["Workspace operations"]
  node_stack_ui["Workspace UI"]
  node_stack_state["Workspace state"]
  node_stack_console["Service console"]
  node_stack_editor["Stack editor"]
end

subgraph group_agents["Agent and Git"]
  node_agent_shell["Agent controls"]
  node_mcp["MCP service"]
  node_pull_requests["Pull requests"]
end

subgraph group_media["Capture and media"]
  node_recording["Screen recording"]
  node_repro["Recording logs"]
  node_capture["Screen capture"]
  node_quick_access["Quick access"]
  node_annotate["Annotation"]
  node_editor["Video editor"]
end

subgraph group_settings["History and settings"]
  node_history[("Capture history")]
  node_preferences["Preferences"]
  node_cloud["Cloud uploads<br/>[CloudManager.swift]"]
end

node_user(("Developer"))
node_cloud_provider["Configured storage"]

node_user -.->|"opens controls"| node_app_shell
node_app_shell -.->|"opens workspaces"| node_stack_ui
node_user -.->|"defines stack"| node_stack_editor
node_stack_ui -.->|"manages"| node_stack_state
node_stack_state -.->|"runs services"| node_stack_console
node_user -.->|"requests agent controls"| node_mcp
node_mcp -.->|"controls workspaces"| node_stack_state
node_agent_shell -.->|"controls workspaces"| node_stack_state
node_stack_console -.->|"supplies workspace logs"| node_repro
node_recording -.->|"records alongside video"| node_repro
node_user -.->|"records screen"| node_recording
node_user -.->|"reviews changes"| node_pull_requests
node_user -.->|"captures screen"| node_capture
node_capture -.->|"adds capture"| node_quick_access
node_quick_access -.->|"opens editing"| node_annotate
node_user -.->|"edits video"| node_editor
node_capture -.->|"stores captures"| node_history
node_user -.->|"configures app"| node_preferences
node_user -.->|"configures uploads"| node_cloud
node_cloud -.->|"uploads optionally"| node_cloud_provider

click node_app_shell "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/App/AppStatusBarController.swift"
click node_stack_ui "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StacksTabView.swift"
click node_stack_state "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StacksViewModel.swift"
click node_stack_console "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StackConsoleViewModel.swift"
click node_stack_editor "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/Components/StackDefinitionEditor.swift"
click node_recording "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Recording/RecordingCoordinator.swift"
click node_repro "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Repro/ReproRecordingController.swift"
click node_agent_shell "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/UnifiedApp/AgentShellController.swift"
click node_mcp "https://github.com/ryancardin15/cinderdeck/blob/main/agent-runtime/apps/server/src/mcp/OrchestratorMcpService.ts"
click node_pull_requests "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/PullRequests/PullRequestsViewModel.swift"
click node_capture "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Capture/ScreenCaptureManager.swift"
click node_quick_access "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/QuickAccess/QuickAccessManager.swift"
click node_annotate "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Annotate/AnnotateManager.swift"
click node_editor "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/VideoEditor/VideoEditorManager.swift"
click node_history "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/History/CaptureHistoryStore.swift"
click node_preferences "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Preferences/PreferencesManager.swift"
click node_cloud "https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Cloud/CloudManager.swift"

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_app_shell toneBlue
class node_stack_ui,node_stack_state,node_stack_console,node_stack_editor,node_cloud_provider toneAmber
class node_agent_shell,node_mcp,node_pull_requests toneMint
class node_recording,node_repro,node_capture,node_quick_access,node_annotate,node_editor toneRose
class node_history,node_preferences,node_cloud,node_user toneIndigo
```

## Components

### App shell

- [Menu bar app](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/App/AppStatusBarController.swift): `Cinderdeck/App/AppStatusBarController.swift`

### Workspace operations

- [Workspace UI](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StacksTabView.swift): `Cinderdeck/Features/Stacks/StacksTabView.swift`
- [Workspace state](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StacksViewModel.swift): `Cinderdeck/Features/Stacks/StacksViewModel.swift`
- [Service console](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/StackConsoleViewModel.swift): `Cinderdeck/Features/Stacks/StackConsoleViewModel.swift`
- [Stack editor](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Stacks/Components/StackDefinitionEditor.swift): `Cinderdeck/Features/Stacks/Components/StackDefinitionEditor.swift`

### Agent and Git

- [Agent controls](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/UnifiedApp/AgentShellController.swift): `Cinderdeck/Services/UnifiedApp/AgentShellController.swift`
- [MCP service](https://github.com/ryancardin15/cinderdeck/blob/main/agent-runtime/apps/server/src/mcp/OrchestratorMcpService.ts): `agent-runtime/apps/server/src/mcp/OrchestratorMcpService.ts`
- [Pull requests](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/PullRequests/PullRequestsViewModel.swift): `Cinderdeck/Features/PullRequests/PullRequestsViewModel.swift`

### Capture and media

- [Screen recording](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Recording/RecordingCoordinator.swift): `Cinderdeck/Features/Recording/RecordingCoordinator.swift`
- [Recording logs](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Repro/ReproRecordingController.swift): `Cinderdeck/Services/Repro/ReproRecordingController.swift`
- [Screen capture](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Capture/ScreenCaptureManager.swift): `Cinderdeck/Services/Capture/ScreenCaptureManager.swift`
- [Quick access](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/QuickAccess/QuickAccessManager.swift): `Cinderdeck/Features/QuickAccess/QuickAccessManager.swift`
- [Annotation](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Annotate/AnnotateManager.swift): `Cinderdeck/Features/Annotate/AnnotateManager.swift`
- [Video editor](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/VideoEditor/VideoEditorManager.swift): `Cinderdeck/Features/VideoEditor/VideoEditorManager.swift`

### History and settings

- [Capture history](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/History/CaptureHistoryStore.swift): `Cinderdeck/Services/History/CaptureHistoryStore.swift`
- [Preferences](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Features/Preferences/PreferencesManager.swift): `Cinderdeck/Features/Preferences/PreferencesManager.swift`
- [Cloud uploads](https://github.com/ryancardin15/cinderdeck/blob/main/Cinderdeck/Services/Cloud/CloudManager.swift): `Cinderdeck/Services/Cloud/CloudManager.swift`

### Other components

- **Developer**
- **Configured storage**

## Connections

- Developer → Menu bar app: opens controls (evidence: `README.md`)
- Menu bar app → Workspace UI: opens workspaces (evidence: `README.md`)
- Developer → Stack editor: defines stack (evidence: `README.md`)
- Workspace UI → Workspace state: manages (evidence: `README.md`)
- Workspace state → Service console: runs services (evidence: `README.md`)
- Developer → MCP service: requests agent controls (evidence: `README.md`)
- MCP service → Workspace state: controls workspaces (evidence: `README.md`)
- Agent controls → Workspace state: controls workspaces (evidence: `README.md`)
- Service console → Recording logs: supplies workspace logs (evidence: `README.md`)
- Screen recording → Recording logs: records alongside video (evidence: `README.md`)
- Developer → Screen recording: records screen (evidence: `README.md`)
- Developer → Pull requests: reviews changes (evidence: `README.md`)
- Developer → Screen capture: captures screen (evidence: `README.md`)
- Screen capture → Quick access: adds capture (evidence: `README.md`)
- Quick access → Annotation: opens editing (evidence: `README.md`)
- Developer → Video editor: edits video (evidence: `README.md`)
- Screen capture → Capture history: stores captures (evidence: `README.md`)
- Developer → Preferences: configures app (evidence: `README.md`)
- Developer → Cloud uploads: configures uploads (evidence: `README.md`)
- Cloud uploads → Configured storage: uploads optionally (evidence: `README.md`)
