# notatestuser/ds4-control architecture

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

- Interactive diagram: https://gitdiagram.com/notatestuser/ds4-control
- Repository: https://github.com/notatestuser/ds4-control

## Overview

DS4 Control is a macOS menu-bar app for choosing and downloading DeepSeek V4/V4.1 models, supervising a local ds4-server, chatting with it, launching coding agents, and viewing system resources. The main workflow runs from the popup’s model selection through feasibility checks, resumable download, and server startup; chat then streams requests to the server. Metrics are sampled independently for the popup widgets. The graph follows README statements and shown source-index references; some implementation details, especially agent launching and settings wiring, were not excerpted.

Main entry points: [`Sources/DS4Control/Services/SupervisorService.swift`](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/SupervisorService.swift) (Server supervisor), [`Sources/DS4Control/Views/PopupView.swift`](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/PopupView.swift) (Control popup), [`Sources/DS4Control/Metrics/MetricsManager.swift`](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/MetricsManager.swift) (Metrics sampler), [`Sources/DS4Control/Services/HFDownloader.swift`](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/HFDownloader.swift) (Model downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Menu Bar UI"]
  node_popup["Control popup<br/>[PopupView.swift]"]
  node_settings["Settings<br/>[SettingsView.swift]"]
  node_chatview["Chat window<br/>[ChatView.swift]"]
  node_markdown["Markdown rendering<br/>[MarkdownText.swift]"]
  node_window["Window activation<br/>[WindowChrome.swift]"]
end

subgraph group_control["App Control"]
  node_app["App composition"]
  node_appstate["Preferences state<br/>[AppState.swift]"]
end

subgraph group_models["Models And Downloads"]
  node_variant["Model variants<br/>[Variant.swift]"]
  node_feasibility["RAM feasibility<br/>[Feasibility.swift]"]
  node_downloader["Model downloader<br/>[HFDownloader.swift]"]
  node_chunkfetch["Range fetching<br/>[ChunkFetcher.swift]"]
  node_chunkbitmap["Resume bitmap<br/>[ChunkBitmap.swift]"]
  node_joiner["GGUF assembly<br/>[GGUFJoiner.swift]"]
end

subgraph group_runtime["Server And Chat"]
  node_serverstate["Server state<br/>[ServerState.swift]"]
  node_supervisor["Server supervisor"]
  node_chatvm["Chat conversation"]
  node_chatservice["Chat streaming<br/>[ChatService.swift]"]
  node_agents["Coding agents"]
end

subgraph group_metrics["Resource Metrics"]
  node_metrics["Metrics sampler"]
  node_cpu["CPU sampling<br/>[CPUCollector.swift]"]
  node_memory["Memory sampling"]
  node_gpu["GPU sampling<br/>[GPUCollector.swift]"]
  node_power["Power sampling"]
end

node_user(("Mac user"))
node_hf(("Hugging Face"))
node_ds4["Local ds4-server"]

node_user -->|"controls"| node_popup
node_app -->|"presents"| node_popup
node_app -->|"opens"| node_settings
node_app -->|"opens"| node_chatview
node_popup -->|"reads preferences"| node_appstate
node_popup -->|"controls server"| node_supervisor
node_popup -->|"shows samples"| node_metrics
node_appstate -->|"selects"| node_variant
node_supervisor -->|"checks launch"| node_feasibility
node_supervisor -->|"uses selection"| node_variant
node_supervisor -->|"downloads weights"| node_downloader
node_downloader -->|"fetches ranges"| node_hf
node_downloader -->|"dispatches chunks"| node_chunkfetch
node_downloader -->|"tracks progress"| node_chunkbitmap
node_supervisor -->|"assembles files"| node_joiner
node_supervisor -->|"starts and monitors"| node_ds4
node_supervisor -->|"publishes state"| node_serverstate
node_chatview -->|"drives conversation"| node_chatvm
node_chatview -->|"renders messages"| node_markdown
node_chatvm -.->|"requests stream"| node_chatservice
node_chatservice -->|"streams completions"| node_ds4
node_metrics -->|"samples"| node_cpu
node_metrics -->|"samples"| node_memory
node_metrics -->|"samples"| node_gpu
node_metrics -->|"samples"| node_power
node_popup -->|"launches agents"| node_agents
node_user -->|"configures"| node_settings
node_settings -.->|"activates window"| node_window

click node_app "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/DS4ControlApp.swift"
click node_popup "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/PopupView.swift"
click node_settings "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/SettingsView.swift"
click node_chatview "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/ChatView.swift"
click node_markdown "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/MarkdownText.swift"
click node_window "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/WindowChrome.swift"
click node_appstate "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/AppState.swift"
click node_variant "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Model/Variant.swift"
click node_feasibility "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Model/Feasibility.swift"
click node_serverstate "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Model/ServerState.swift"
click node_supervisor "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/SupervisorService.swift"
click node_downloader "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/HFDownloader.swift"
click node_chunkfetch "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/ChunkFetcher.swift"
click node_chunkbitmap "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/ChunkBitmap.swift"
click node_joiner "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/GGUFJoiner.swift"
click node_chatvm "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/ViewModels/ChatViewModel.swift"
click node_chatservice "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/ChatService.swift"
click node_metrics "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/MetricsManager.swift"
click node_cpu "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/CPUCollector.swift"
click node_memory "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/MemoryCollector.swift"
click node_gpu "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/GPUCollector.swift"
click node_power "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/PowerCollector.swift"
click node_agents "https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/AgentLauncher.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_popup,node_settings,node_chatview,node_markdown,node_window,node_user toneBlue
class node_app,node_appstate toneAmber
class node_variant,node_feasibility,node_downloader,node_chunkfetch,node_chunkbitmap,node_joiner,node_ds4 toneMint
class node_serverstate,node_supervisor,node_chatvm,node_chatservice,node_agents toneRose
class node_metrics,node_cpu,node_memory,node_gpu,node_power,node_hf toneIndigo
```

## Components

### Menu Bar UI

- [Control popup](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/PopupView.swift): `Sources/DS4Control/Views/PopupView.swift`
- [Settings](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/SettingsView.swift): `Sources/DS4Control/Views/SettingsView.swift`
- [Chat window](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/ChatView.swift): `Sources/DS4Control/Views/ChatView.swift`
- [Markdown rendering](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Views/MarkdownText.swift): `Sources/DS4Control/Views/MarkdownText.swift`
- [Window activation](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/WindowChrome.swift): `Sources/DS4Control/WindowChrome.swift`

### App Control

- [App composition](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/DS4ControlApp.swift): `Sources/DS4Control/DS4ControlApp.swift`
- [Preferences state](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/AppState.swift): `Sources/DS4Control/AppState.swift`

### Models And Downloads

- [Model variants](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Model/Variant.swift): `Sources/DS4Control/Model/Variant.swift`
- [RAM feasibility](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Model/Feasibility.swift): `Sources/DS4Control/Model/Feasibility.swift`
- [Model downloader](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/HFDownloader.swift): `Sources/DS4Control/Services/HFDownloader.swift`
- [Range fetching](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/ChunkFetcher.swift): `Sources/DS4Control/Services/ChunkFetcher.swift`
- [Resume bitmap](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/ChunkBitmap.swift): `Sources/DS4Control/Services/ChunkBitmap.swift`
- [GGUF assembly](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/GGUFJoiner.swift): `Sources/DS4Control/Services/GGUFJoiner.swift`

### Server And Chat

- [Server state](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Model/ServerState.swift): `Sources/DS4Control/Model/ServerState.swift`
- [Server supervisor](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/SupervisorService.swift): `Sources/DS4Control/Services/SupervisorService.swift`
- [Chat conversation](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/ViewModels/ChatViewModel.swift): `Sources/DS4Control/ViewModels/ChatViewModel.swift`
- [Chat streaming](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/ChatService.swift): `Sources/DS4Control/Services/ChatService.swift`
- [Coding agents](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Services/AgentLauncher.swift): `Sources/DS4Control/Services/AgentLauncher.swift`

### Resource Metrics

- [Metrics sampler](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/MetricsManager.swift): `Sources/DS4Control/Metrics/MetricsManager.swift`
- [CPU sampling](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/CPUCollector.swift): `Sources/DS4Control/Metrics/CPUCollector.swift`
- [Memory sampling](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/MemoryCollector.swift): `Sources/DS4Control/Metrics/MemoryCollector.swift`
- [GPU sampling](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/GPUCollector.swift): `Sources/DS4Control/Metrics/GPUCollector.swift`
- [Power sampling](https://github.com/notatestuser/ds4-control/blob/main/Sources/DS4Control/Metrics/PowerCollector.swift): `Sources/DS4Control/Metrics/PowerCollector.swift`

### Other components

- **Mac user**
- **Hugging Face**
- **Local ds4-server**

## Connections

- Mac user → Control popup: controls (evidence: `README.md`)
- App composition → Control popup: presents (evidence: `Sources/DS4Control/DS4ControlApp.swift`)
- App composition → Settings: opens (evidence: `Sources/DS4Control/DS4ControlApp.swift`)
- App composition → Chat window: opens (evidence: `Sources/DS4Control/DS4ControlApp.swift`)
- Control popup → Preferences state: reads preferences (evidence: `Sources/DS4Control/Views/PopupView.swift`)
- Control popup → Server supervisor: controls server (evidence: `Sources/DS4Control/Views/PopupView.swift`)
- Control popup → Metrics sampler: shows samples (evidence: `Sources/DS4Control/Views/PopupView.swift`)
- Preferences state → Model variants: selects (evidence: `Sources/DS4Control/AppState.swift`)
- Server supervisor → RAM feasibility: checks launch (evidence: `Sources/DS4Control/Services/SupervisorService.swift`)
- Server supervisor → Model variants: uses selection (evidence: `Sources/DS4Control/Services/SupervisorService.swift`)
- Server supervisor → Model downloader: downloads weights (evidence: `README.md`)
- Model downloader → Hugging Face: fetches ranges (evidence: `Sources/DS4Control/Services/HFDownloader.swift`)
- Model downloader → Range fetching: dispatches chunks (evidence: `Sources/DS4Control/Services/HFDownloader.swift`)
- Model downloader → Resume bitmap: tracks progress (evidence: `Sources/DS4Control/Services/HFDownloader.swift`)
- Server supervisor → GGUF assembly: assembles files (evidence: `Sources/DS4Control/Services/SupervisorService.swift`)
- Server supervisor → Local ds4-server: starts and monitors (evidence: `README.md`)
- Server supervisor → Server state: publishes state (evidence: `Sources/DS4Control/Services/SupervisorService.swift`)
- Chat window → Chat conversation: drives conversation (evidence: `Sources/DS4Control/Views/ChatView.swift`)
- Chat window → Markdown rendering: renders messages (evidence: `Sources/DS4Control/Views/ChatView.swift`)
- Chat conversation → Chat streaming: requests stream
- Chat streaming → Local ds4-server: streams completions (evidence: `README.md`)
- Metrics sampler → CPU sampling: samples (evidence: `Sources/DS4Control/Metrics/MetricsManager.swift`)
- Metrics sampler → Memory sampling: samples (evidence: `Sources/DS4Control/Metrics/MetricsManager.swift`)
- Metrics sampler → GPU sampling: samples (evidence: `Sources/DS4Control/Metrics/MetricsManager.swift`)
- Metrics sampler → Power sampling: samples (evidence: `Sources/DS4Control/Metrics/MetricsManager.swift`)
- Control popup → Coding agents: launches agents (evidence: `Sources/DS4Control/Views/PopupView.swift`)
- Mac user → Settings: configures (evidence: `README.md`)
- Settings → Window activation: activates window (evidence: `Sources/DS4Control/Views/SettingsView.swift`)