# codejunkie99/agentic-stack-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/codejunkie99/agentic-stack-desktop
- Repository: https://github.com/codejunkie99/agentic-stack-desktop

## Overview

Agentic Stack is a local-first macOS workspace and backend that unifies coding-agent conversations, project work, and reusable memory. The main workflow runs from a user composing work in the desktop app through its bridge to workspace services, which coordinate model selection and agent execution; approved knowledge and conversation evidence can then be searched or recalled across tools. The README documents additional loops, terminals, setup, and operations. Several backend paths are represented from documented capabilities and the tree; unsampled internal wiring is left unspecified.

Main entry points: [`apps/macos/Sources/AgenticWorkspaces/AppModel.swift`](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/AppModel.swift) (App Model), [`harness_manager/workspaces/service.py`](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/service.py) (Workspace Service), [`harness_manager/context_mcp.py`](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/context_mcp.py) (Context MCP), [`apps/macos/Sources/AgenticWorkspaces/Bridge.swift`](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/Bridge.swift) (Backend Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["macOS Workspace"]
  node_desktop_app["Desktop App"]
  node_app_model["App Model<br/>[AppModel.swift]"]
  node_conversation_ui["Conversation UI"]
  node_knowledge_ui["Knowledge Views"]
  node_bridge["Backend Bridge<br/>[Bridge.swift]"]
end

subgraph group_backend["Workspace Backend"]
  node_workspace_server["HTTP Bridge<br/>[server.py]"]
  node_workspace_service["Workspace Service<br/>[service.py]"]
  node_model_router["Model Router<br/>[model_router.py]"]
  node_workspace_store[("Workspace Store<br/>[store.py]")]
  node_task_stream["Task Streams<br/>[task_stream.py]"]
  node_loop_runner["Loop Coordinator<br/>[runner.py]"]
  node_loop_state[("Loop Checkpoints<br/>[storage.py]")]
end

subgraph group_knowledge["Shared Context"]
  node_knowledge_import["Knowledge Import<br/>[knowledge.py]"]
  node_personal_memory["Personal Memory<br/>[personal_memory.py]"]
  node_context_mcp["Context MCP<br/>[context_mcp.py]"]
end

subgraph group_operations["Projects and Operations"]
  node_project_setup["Project Setup<br/>[setup.py]"]
  node_terminal["Interactive Terminals<br/>[terminal.py]"]
  node_mission_control["Mission Control<br/>[mission_control.py]"]
end

node_user(("User"))
node_conversation_sources[("Agent Histories")]
node_agents(("Coding Agents"))
node_server_host(("Private Server"))

node_user -->|"uses"| node_desktop_app
node_desktop_app -->|"hosts"| node_app_model
node_app_model -->|"presents"| node_conversation_ui
node_conversation_ui -->|"submits work"| node_app_model
node_app_model -->|"sends requests"| node_bridge
node_bridge -->|"RPC requests"| node_workspace_server
node_server_host -.->|"hosts service"| node_workspace_server
node_workspace_server -->|"dispatches"| node_workspace_service
node_workspace_service -->|"reads and writes"| node_workspace_store
node_workspace_service -->|"selects model"| node_model_router
node_workspace_service -->|"streams progress"| node_task_stream
node_workspace_service -->|"runs tasks"| node_agents
node_workspace_service -->|"imports approved sources"| node_knowledge_import
node_workspace_service -->|"manages profile"| node_personal_memory
node_knowledge_ui -->|"requests graph data"| node_app_model
node_app_model -->|"requests knowledge"| node_bridge
node_context_mcp -->|"reads history"| node_conversation_sources
node_context_mcp -->|"reads indexed memory"| node_workspace_store
node_agents -.->|"recalls context"| node_context_mcp
node_loop_runner -->|"stores checkpoints"| node_loop_state
node_app_model -->|"requests setup"| node_project_setup
node_app_model -->|"controls terminal"| node_terminal
node_app_model -->|"requests operations"| node_mission_control

click node_desktop_app "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/AgenticWorkspacesApp.swift"
click node_app_model "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/AppModel.swift"
click node_conversation_ui "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/ConversationView.swift"
click node_knowledge_ui "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/KnowledgeGraphView.swift"
click node_bridge "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/Bridge.swift"
click node_workspace_server "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/server.py"
click node_workspace_service "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/service.py"
click node_model_router "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/model_router.py"
click node_workspace_store "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/store.py"
click node_task_stream "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/task_stream.py"
click node_loop_runner "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/loops/runner.py"
click node_loop_state "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/loops/storage.py"
click node_knowledge_import "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/knowledge.py"
click node_personal_memory "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/personal_memory.py"
click node_context_mcp "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/context_mcp.py"
click node_project_setup "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/setup.py"
click node_terminal "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/terminal.py"
click node_mission_control "https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/mission_control.py"

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_app_model,node_conversation_ui,node_knowledge_ui,node_bridge,node_user toneBlue
class node_workspace_server,node_workspace_service,node_model_router,node_workspace_store,node_task_stream,node_loop_runner,node_loop_state,node_conversation_sources toneAmber
class node_knowledge_import,node_personal_memory,node_context_mcp,node_server_host toneMint
class node_project_setup,node_terminal,node_mission_control toneRose
class node_agents toneIndigo
```

## Components

### macOS Workspace

- [Desktop App](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/AgenticWorkspacesApp.swift): `apps/macos/Sources/AgenticWorkspaces/AgenticWorkspacesApp.swift`
- [App Model](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/AppModel.swift): `apps/macos/Sources/AgenticWorkspaces/AppModel.swift`
- [Conversation UI](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/ConversationView.swift): `apps/macos/Sources/AgenticWorkspaces/ConversationView.swift`
- [Knowledge Views](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/KnowledgeGraphView.swift): `apps/macos/Sources/AgenticWorkspaces/KnowledgeGraphView.swift`
- [Backend Bridge](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/apps/macos/Sources/AgenticWorkspaces/Bridge.swift): `apps/macos/Sources/AgenticWorkspaces/Bridge.swift`

### Workspace Backend

- [HTTP Bridge](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/server.py): `harness_manager/workspaces/server.py`
- [Workspace Service](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/service.py): `harness_manager/workspaces/service.py`
- [Model Router](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/model_router.py): `harness_manager/workspaces/model_router.py`
- [Workspace Store](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/store.py): `harness_manager/workspaces/store.py`
- [Task Streams](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/task_stream.py): `harness_manager/workspaces/task_stream.py`
- [Loop Coordinator](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/loops/runner.py): `harness_manager/loops/runner.py`
- [Loop Checkpoints](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/loops/storage.py): `harness_manager/loops/storage.py`

### Shared Context

- [Knowledge Import](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/knowledge.py): `harness_manager/workspaces/knowledge.py`
- [Personal Memory](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/personal_memory.py): `harness_manager/workspaces/personal_memory.py`
- [Context MCP](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/context_mcp.py): `harness_manager/context_mcp.py`

### Projects and Operations

- [Project Setup](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/setup.py): `harness_manager/workspaces/setup.py`
- [Interactive Terminals](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/workspaces/terminal.py): `harness_manager/workspaces/terminal.py`
- [Mission Control](https://github.com/codejunkie99/agentic-stack-desktop/blob/main/harness_manager/mission_control.py): `harness_manager/mission_control.py`

### Other components

- **User**
- **Agent Histories**
- **Coding Agents**
- **Private Server**

## Connections

- User → Desktop App: uses
- Desktop App → App Model: hosts
- App Model → Conversation UI: presents
- Conversation UI → App Model: submits work
- App Model → Backend Bridge: sends requests
- Backend Bridge → HTTP Bridge: RPC requests
- Private Server → HTTP Bridge: hosts service
- HTTP Bridge → Workspace Service: dispatches
- Workspace Service → Workspace Store: reads and writes
- Workspace Service → Model Router: selects model
- Workspace Service → Task Streams: streams progress
- Workspace Service → Coding Agents: runs tasks
- Workspace Service → Knowledge Import: imports approved sources
- Workspace Service → Personal Memory: manages profile
- Knowledge Views → App Model: requests graph data
- App Model → Backend Bridge: requests knowledge
- Context MCP → Agent Histories: reads history
- Context MCP → Workspace Store: reads indexed memory
- Coding Agents → Context MCP: recalls context
- Loop Coordinator → Loop Checkpoints: stores checkpoints
- App Model → Project Setup: requests setup
- App Model → Interactive Terminals: controls terminal
- App Model → Mission Control: requests operations