# witnesstodark/mr-mak-workspace architecture

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

- Interactive diagram: https://gitdiagram.com/witnesstodark/mr-mak-workspace
- Repository: https://github.com/witnesstodark/mr-mak-workspace

## Overview

Mr. Mak combines CLI-agent chats, a project Workspace, and a paired-phone interface. The main workflow is a user starting or continuing an agent session in Chats, monitoring its terminal or transcript, then reviewing project reports and files in Workspace; the phone can follow conversations and send input while agents continue on the computer. The graph keeps these product stages and supporting session, project, and API layers distinct. Edges are limited to relationships shown in the excerpts, source index, or README; several feature nodes use exact directories because their implementations were not sampled.

Main entry points: [`desktop/service/server.mjs`](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/server.mjs) (Service API), [`src/App.tsx`](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/App.tsx) (Workspace UI), [`src/desktop/client.ts`](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/client.ts) (Desktop API client), [`desktop/service/sessions.mjs`](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/sessions.mjs) (Agent sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop chats"]
  node_desktop_app["Desktop UI<br/>[DesktopApp.tsx]"]
  node_chat_views["Chat views<br/>[Conversation.tsx]"]
  node_terminal["CLI terminal<br/>[TerminalPane.tsx]"]
  node_desktop_client["Desktop API client<br/>[client.ts]"]
end

subgraph group_service["Agent service"]
  node_sessions["Agent sessions<br/>[sessions.mjs]"]
  node_agent_adapters["Agent adapters<br/>[agents.mjs]"]
  node_coordinator["Voice coordinator<br/>[coordinator.mjs]"]
  node_service_server["Service API<br/>[server.mjs]"]
  node_service_state[("Service state<br/>[util.mjs]")]
end

subgraph group_workspace["Project workspace"]
  node_workspace_ui["Workspace UI<br/>[App.tsx]"]
  node_workspace_data["Workspace data<br/>[workspace.ts]"]
  node_card_editor["Card editor<br/>[EditableCard.tsx]"]
  node_report_viewer["Report viewer<br/>[ReportViewer.tsx]"]
  node_project_files["Project files<br/>[files.mjs]"]
end

subgraph group_mobile["Phone access"]
  node_mobile_ui["Mobile app<br/>[MobileApp.tsx]"]
  node_mobile_client["Mobile API client<br/>[client.ts]"]
  node_mobile_service["Mobile access<br/>[mobile.mjs]"]
  node_mobile_dictation["Mobile dictation"]
  node_tailscale{{"Tailscale"}}
end

node_user(("User"))

node_user -->|"uses"| node_desktop_app
node_desktop_app -.->|"shows"| node_chat_views
node_user -->|"sends tasks"| node_chat_views
node_chat_views -.->|"sends requests"| node_desktop_client
node_terminal -->|"runs sessions"| node_sessions
node_sessions -->|"uses"| node_agent_adapters
node_desktop_client -->|"calls API"| node_service_server
node_service_server -->|"routes to"| node_sessions
node_service_server -->|"dispatches"| node_coordinator
node_coordinator -->|"executes agents"| node_agent_adapters
node_service_server -->|"reads and writes"| node_service_state
node_user -->|"reviews results"| node_workspace_ui
node_workspace_ui -->|"loads"| node_workspace_data
node_workspace_data -->|"requests data"| node_desktop_client
node_workspace_ui -->|"renders"| node_report_viewer
node_workspace_ui -->|"edits cards"| node_card_editor
node_card_editor -->|"saves via"| node_desktop_client
node_service_server -->|"routes file work"| node_project_files
node_user -->|"uses phone"| node_mobile_ui
node_mobile_ui -.->|"requests data"| node_mobile_client
node_mobile_client -->|"calls API"| node_mobile_service
node_mobile_service -.->|"shares chats"| node_sessions
node_mobile_service -.->|"supports dictation"| node_mobile_dictation
node_mobile_ui -->|"connects through"| node_tailscale

click node_desktop_app "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/DesktopApp.tsx"
click node_chat_views "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/Conversation.tsx"
click node_terminal "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/TerminalPane.tsx"
click node_desktop_client "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/client.ts"
click node_sessions "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/sessions.mjs"
click node_agent_adapters "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/agents.mjs"
click node_coordinator "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/coordinator.mjs"
click node_service_server "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/server.mjs"
click node_service_state "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/util.mjs"
click node_workspace_ui "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/App.tsx"
click node_workspace_data "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/lib/workspace.ts"
click node_card_editor "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/components/EditableCard.tsx"
click node_report_viewer "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/components/ReportViewer.tsx"
click node_project_files "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/files.mjs"
click node_mobile_ui "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/mobile/MobileApp.tsx"
click node_mobile_client "https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/mobile/client.ts"
click node_mobile_service "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/mobile.mjs"
click node_mobile_dictation "https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/mobile-dictation.mjs"

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_desktop_app,node_chat_views,node_terminal,node_desktop_client,node_user toneBlue
class node_sessions,node_agent_adapters,node_coordinator,node_service_server,node_service_state toneAmber
class node_workspace_ui,node_workspace_data,node_card_editor,node_report_viewer,node_project_files toneMint
class node_mobile_ui,node_mobile_client,node_mobile_service,node_mobile_dictation,node_tailscale toneRose
```

## Components

### Desktop chats

- [Desktop UI](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/DesktopApp.tsx): `src/desktop/DesktopApp.tsx`
- [Chat views](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/Conversation.tsx): `src/desktop/Conversation.tsx`
- [CLI terminal](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/TerminalPane.tsx): `src/desktop/TerminalPane.tsx`
- [Desktop API client](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/desktop/client.ts): `src/desktop/client.ts`

### Agent service

- [Agent sessions](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/sessions.mjs): `desktop/service/sessions.mjs`
- [Agent adapters](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/agents.mjs): `desktop/service/agents.mjs`
- [Voice coordinator](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/coordinator.mjs): `desktop/service/coordinator.mjs`
- [Service API](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/server.mjs): `desktop/service/server.mjs`
- [Service state](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/util.mjs): `desktop/service/util.mjs`

### Project workspace

- [Workspace UI](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/App.tsx): `src/App.tsx`
- [Workspace data](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/lib/workspace.ts): `src/lib/workspace.ts`
- [Card editor](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/components/EditableCard.tsx): `src/components/EditableCard.tsx`
- [Report viewer](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/components/ReportViewer.tsx): `src/components/ReportViewer.tsx`
- [Project files](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/files.mjs): `desktop/service/files.mjs`

### Phone access

- [Mobile app](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/mobile/MobileApp.tsx): `src/mobile/MobileApp.tsx`
- [Mobile API client](https://github.com/witnesstodark/mr-mak-workspace/blob/main/src/mobile/client.ts): `src/mobile/client.ts`
- [Mobile access](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/mobile.mjs): `desktop/service/mobile.mjs`
- [Mobile dictation](https://github.com/witnesstodark/mr-mak-workspace/blob/main/desktop/service/mobile-dictation.mjs): `desktop/service/mobile-dictation.mjs`
- **Tailscale**

### Other components

- **User**

## Connections

- User → Desktop UI: uses
- Desktop UI → Chat views: shows
- User → Chat views: sends tasks
- Chat views → Desktop API client: sends requests
- CLI terminal → Agent sessions: runs sessions
- Agent sessions → Agent adapters: uses (evidence: `desktop/service/sessions.mjs`)
- Desktop API client → Service API: calls API (evidence: `src/desktop/client.ts`)
- Service API → Agent sessions: routes to (evidence: `desktop/service/server.mjs`)
- Service API → Voice coordinator: dispatches (evidence: `desktop/service/server.mjs`)
- Voice coordinator → Agent adapters: executes agents (evidence: `desktop/service/coordinator.mjs`)
- Service API → Service state: reads and writes (evidence: `desktop/service/server.mjs`)
- User → Workspace UI: reviews results
- Workspace UI → Workspace data: loads (evidence: `src/App.tsx`)
- Workspace data → Desktop API client: requests data (evidence: `src/lib/workspace.ts`)
- Workspace UI → Report viewer: renders (evidence: `src/App.tsx`)
- Workspace UI → Card editor: edits cards (evidence: `src/App.tsx`)
- Card editor → Desktop API client: saves via (evidence: `src/components/EditableCard.tsx`)
- Service API → Project files: routes file work (evidence: `desktop/service/server.mjs`)
- User → Mobile app: uses phone
- Mobile app → Mobile API client: requests data
- Mobile API client → Mobile access: calls API (evidence: `src/mobile/client.ts`)
- Mobile access → Agent sessions: shares chats
- Mobile access → Mobile dictation: supports dictation
- Mobile app → Tailscale: connects through