# ak6062042-commits/digital-workspace-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ak6062042-commits/digital-workspace-agent
- Repository: https://github.com/ak6062042-commits/digital-workspace-agent

## Overview

Digital Workspace Agent is a local-first assistant for workspace context, task organization, research, and writing help, with user-controlled action boundaries. The main workflow runs from a dashboard or companion client through the authenticated FastAPI control plane: chat is routed through context, planning, and policy-enforcing execution; optional context capture is redacted and persisted for state views and task linking. Major client integrations and capabilities documented in the README are included. Several subsystem links rely on README descriptions because their implementation excerpts were not provided.

Main entry points: [`backend/main.py`](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/main.py) (FastAPI Control Plane), [`backend/orchestration/executor.py`](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/orchestration/executor.py) (Policy Executor), [`backend/coordinator/router.py`](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/router.py) (Coordinator Router), [`backend/db/db.py`](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/db/db.py) (SQLite Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_dashboard["React Dashboard<br/>[App.jsx]"]
  node_chat["Chat Interface<br/>[ChatWindow.jsx]"]
  node_api_client["API Client<br/>[client.js]"]
  node_widget["Desktop Widget<br/>[widget.py]"]
  node_chrome["Chrome Companion<br/>[popup.js]"]
  node_word["Word Task Pane<br/>[taskpane.js]"]
end

subgraph group_control["Control Plane"]
  node_api["FastAPI Control Plane<br/>[main.py]"]
  node_security["Request Security<br/>[security.py]"]
  node_privacy["Privacy Filtering<br/>[privacy.py]"]
end

subgraph group_workflow["Assistant Workflow"]
  node_router["Coordinator Router<br/>[router.py]"]
  node_context["Session Context<br/>[context_store.py]"]
  node_planner["Intent Planner<br/>[planner.py]"]
  node_executor["Policy Executor<br/>[executor.py]"]
  node_state_agent["State Agent<br/>[state_agent.py]"]
  node_task_agent["Task Agent<br/>[task_agent.py]"]
  node_web_agent["Research Agent<br/>[web_agent.py]"]
  node_scheduler["Suggestion Scheduler<br/>[scheduler.py]"]
end

subgraph group_data["Workspace Data"]
  node_database[("SQLite Database<br/>[db.py]")]
  node_models["Workspace Records<br/>[models.py]"]
end

subgraph group_integrations["Local Integrations"]
  node_watcher["Local State Watcher<br/>[watcher.py]"]
  node_browser_tool["Browser Actions<br/>[browser_tool.py]"]
  node_os_tool["Desktop Actions<br/>[os_tool.py]"]
  node_search_tool["Web Search<br/>[search_tool.py]"]
  node_fetch_tool["Page Fetching<br/>[fetch_tool.py]"]
end

node_user(("Workspace User"))
node_external_search(("Search Providers"))

node_user -->|"uses"| node_dashboard
node_user -->|"uses"| node_widget
node_user -->|"uses"| node_chrome
node_user -->|"uses"| node_word
node_dashboard -->|"renders"| node_chat
node_dashboard -->|"requests through"| node_api_client
node_chat -->|"sends requests"| node_api_client
node_api_client -->|"calls API"| node_api
node_widget -->|"uses authenticated API"| node_api
node_chrome -.->|"syncs opt-in context"| node_api
node_word -.->|"submits selected text"| node_api
node_watcher -.->|"submits snapshots"| node_api
node_api -->|"guards requests"| node_security
node_api -->|"routes chat"| node_router
node_router -->|"reads latest state"| node_state_agent
node_router -->|"records messages"| node_context
node_router -->|"plans request"| node_planner
node_router -->|"executes plan"| node_executor
node_executor -->|"delegates state"| node_state_agent
node_executor -->|"delegates tasks"| node_task_agent
node_executor -->|"delegates research"| node_web_agent
node_executor -->|"opens URLs"| node_browser_tool
node_executor -->|"launches apps"| node_os_tool
node_web_agent -->|"searches web"| node_search_tool
node_web_agent -->|"fetches pages"| node_fetch_tool
node_search_tool -->|"queries providers"| node_external_search
node_state_agent -->|"reads snapshots"| node_database
node_task_agent -.->|"manages tasks"| node_database
node_api -.->|"persists workspace data"| node_database
node_database -->|"stores records"| node_models
node_api -->|"redacts data"| node_privacy
node_scheduler -.->|"reads and writes suggestions"| node_database

click node_dashboard "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/frontend/src/App.jsx"
click node_chat "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/frontend/src/components/ChatWindow.jsx"
click node_api_client "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/frontend/src/api/client.js"
click node_widget "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/floating-widget/widget.py"
click node_chrome "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/browser-extension/popup.js"
click node_word "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/word-addin/taskpane.js"
click node_api "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/main.py"
click node_security "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/core/security.py"
click node_privacy "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/core/privacy.py"
click node_router "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/router.py"
click node_context "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/context_store.py"
click node_planner "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/orchestration/planner.py"
click node_executor "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/orchestration/executor.py"
click node_state_agent "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/agents/state_agent.py"
click node_task_agent "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/agents/task_agent.py"
click node_web_agent "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/agents/web_agent.py"
click node_scheduler "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/scheduler.py"
click node_database "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/db/db.py"
click node_models "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/db/models.py"
click node_watcher "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/local-agent/watcher.py"
click node_browser_tool "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/browser_tool.py"
click node_os_tool "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/os_tool.py"
click node_search_tool "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/search_tool.py"
click node_fetch_tool "https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/fetch_tool.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_dashboard,node_chat,node_api_client,node_widget,node_chrome,node_word,node_user toneBlue
class node_api,node_security,node_privacy toneAmber
class node_router,node_context,node_planner,node_executor,node_state_agent,node_task_agent,node_web_agent,node_scheduler toneMint
class node_database,node_models toneRose
class node_watcher,node_browser_tool,node_os_tool,node_search_tool,node_fetch_tool,node_external_search toneIndigo
```

## Components

### User Clients

- [React Dashboard](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat Interface](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/frontend/src/components/ChatWindow.jsx): `frontend/src/components/ChatWindow.jsx`
- [API Client](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Desktop Widget](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/floating-widget/widget.py): `system-agent/floating-widget/widget.py`
- [Chrome Companion](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/browser-extension/popup.js): `system-agent/browser-extension/popup.js`
- [Word Task Pane](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/word-addin/taskpane.js): `system-agent/word-addin/taskpane.js`

### Control Plane

- [FastAPI Control Plane](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/main.py): `backend/main.py`
- [Request Security](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/core/security.py): `backend/core/security.py`
- [Privacy Filtering](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/core/privacy.py): `backend/core/privacy.py`

### Assistant Workflow

- [Coordinator Router](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/router.py): `backend/coordinator/router.py`
- [Session Context](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/context_store.py): `backend/coordinator/context_store.py`
- [Intent Planner](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/orchestration/planner.py): `backend/orchestration/planner.py`
- [Policy Executor](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/orchestration/executor.py): `backend/orchestration/executor.py`
- [State Agent](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/agents/state_agent.py): `backend/agents/state_agent.py`
- [Task Agent](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/agents/task_agent.py): `backend/agents/task_agent.py`
- [Research Agent](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/agents/web_agent.py): `backend/agents/web_agent.py`
- [Suggestion Scheduler](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/coordinator/scheduler.py): `backend/coordinator/scheduler.py`

### Workspace Data

- [SQLite Database](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/db/db.py): `backend/db/db.py`
- [Workspace Records](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/db/models.py): `backend/db/models.py`

### Local Integrations

- [Local State Watcher](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/system-agent/local-agent/watcher.py): `system-agent/local-agent/watcher.py`
- [Browser Actions](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/browser_tool.py): `backend/tools/browser_tool.py`
- [Desktop Actions](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/os_tool.py): `backend/tools/os_tool.py`
- [Web Search](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/search_tool.py): `backend/tools/search_tool.py`
- [Page Fetching](https://github.com/ak6062042-commits/digital-workspace-agent/blob/main/backend/tools/fetch_tool.py): `backend/tools/fetch_tool.py`

### Other components

- **Workspace User**
- **Search Providers**

## Connections

- Workspace User → React Dashboard: uses (evidence: `README.md`)
- Workspace User → Desktop Widget: uses (evidence: `README.md`)
- Workspace User → Chrome Companion: uses (evidence: `README.md`)
- Workspace User → Word Task Pane: uses (evidence: `README.md`)
- React Dashboard → Chat Interface: renders (evidence: `frontend/src/App.jsx`)
- React Dashboard → API Client: requests through (evidence: `frontend/src/App.jsx`)
- Chat Interface → API Client: sends requests (evidence: `frontend/src/components/ChatWindow.jsx`)
- API Client → FastAPI Control Plane: calls API (evidence: `frontend/src/api/client.js`)
- Desktop Widget → FastAPI Control Plane: uses authenticated API (evidence: `README.md`)
- Chrome Companion → FastAPI Control Plane: syncs opt-in context (evidence: `README.md`)
- Word Task Pane → FastAPI Control Plane: submits selected text (evidence: `README.md`)
- Local State Watcher → FastAPI Control Plane: submits snapshots (evidence: `README.md`)
- FastAPI Control Plane → Request Security: guards requests (evidence: `README.md`)
- FastAPI Control Plane → Coordinator Router: routes chat (evidence: `backend/main.py`)
- Coordinator Router → State Agent: reads latest state (evidence: `backend/coordinator/router.py`)
- Coordinator Router → Session Context: records messages (evidence: `backend/coordinator/router.py`)
- Coordinator Router → Intent Planner: plans request (evidence: `backend/coordinator/router.py`)
- Coordinator Router → Policy Executor: executes plan (evidence: `backend/coordinator/router.py`)
- Policy Executor → State Agent: delegates state (evidence: `backend/orchestration/executor.py`)
- Policy Executor → Task Agent: delegates tasks (evidence: `backend/orchestration/executor.py`)
- Policy Executor → Research Agent: delegates research (evidence: `backend/orchestration/executor.py`)
- Policy Executor → Browser Actions: opens URLs (evidence: `backend/orchestration/executor.py`)
- Policy Executor → Desktop Actions: launches apps (evidence: `backend/orchestration/executor.py`)
- Research Agent → Web Search: searches web (evidence: `backend/agents/web_agent.py`)
- Research Agent → Page Fetching: fetches pages (evidence: `backend/agents/web_agent.py`)
- Web Search → Search Providers: queries providers (evidence: `backend/tools/search_tool.py`)
- State Agent → SQLite Database: reads snapshots (evidence: `backend/agents/state_agent.py`)
- Task Agent → SQLite Database: manages tasks (evidence: `backend/agents/task_agent.py`)
- FastAPI Control Plane → SQLite Database: persists workspace data (evidence: `README.md`)
- SQLite Database → Workspace Records: stores records (evidence: `backend/db/db.py`)
- FastAPI Control Plane → Privacy Filtering: redacts data (evidence: `README.md`)
- Suggestion Scheduler → SQLite Database: reads and writes suggestions (evidence: `backend/coordinator/scheduler.py`)