# 2sincejuly/skydot architecture

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

- Interactive diagram: https://gitdiagram.com/2sincejuly/skydot
- Repository: https://github.com/2sincejuly/skydot

## Overview

SkyDot is a self-hosted multi-user agent workspace: users configure a Dot and workspace, submit conversations or scheduled work, and receive streamed results, collaboration updates, or approval requests. The documented execution boundary places orchestration and persistence in the backend and agent work in a Host or Docker runner; the shared web client is also used by PWA and Electron. The README supports the major capability branches shown here. Some subsystem links are documented rather than verified in sampled implementation, so those edges cite the README.

Main entry points: [`src/index.ts`](https://github.com/2sincejuly/skydot/blob/main/src/index.ts) (Backend Service), [`container/agent-runner/src/index.ts`](https://github.com/2sincejuly/skydot/blob/main/container/agent-runner/src/index.ts) (Agent Runner), [`web/src/App.tsx`](https://github.com/2sincejuly/skydot/blob/main/web/src/App.tsx) (Web and PWA), [`src/personal-agent/product-runtime-store.ts`](https://github.com/2sincejuly/skydot/blob/main/src/personal-agent/product-runtime-store.ts) (Product Runtime State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_web["Web and PWA<br/>[App.tsx]"]
  node_electron["Electron Desktop<br/>[index.ts]"]
end

subgraph group_backend["Backend Control Plane"]
  node_auth["Authentication and ACL<br/>[auth.ts]"]
  node_backend_entry["Backend Service<br/>[index.ts]"]
  node_database[("SQLite Persistence<br/>[db.ts]")]
  node_im_channels["Channel Connections<br/>[im-manager.ts]"]
  node_tasks["Task Scheduling<br/>[task-scheduler.ts]"]
  node_runtime_store[("Product Runtime State")]
end

subgraph group_execution["Agent Execution"]
  node_runner["Agent Runner<br/>[index.ts]"]
  node_pi_runtime["Pi Runtime<br/>[pi-runtime.ts]"]
  node_cloud_runtime["Cloud Runtime<br/>[session-object.ts]"]
end

subgraph group_collaboration["Collaboration"]
  node_groups["Group Discussions"]
  node_handoffs["Bot Handoffs<br/>[handoff-service.ts]"]
end

subgraph group_capabilities["Work Capabilities"]
  node_skills_plugins["Skills and Plugins<br/>[plugin-catalog.ts]"]
  node_mcp["MCP Integrations<br/>[mcp-client.ts]"]
  node_memory["Workspace Memory<br/>[memory-service.ts]"]
  node_goals["Goals and Durable Work<br/>[goal-runtime.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"requests backend"| node_auth
node_electron -->|"shares frontend"| node_web
node_auth -.->|"guards access"| node_backend_entry
node_backend_entry -->|"persists state"| node_database
node_backend_entry -->|"dispatches execution"| node_runner
node_runner -->|"runs agent"| node_pi_runtime
node_backend_entry -->|"connects channels"| node_im_channels
node_im_channels -->|"routes messages"| node_backend_entry
node_backend_entry -->|"schedules work"| node_tasks
node_tasks -.->|"starts runs"| node_runner
node_backend_entry -.->|"serves collaboration"| node_groups
node_groups -->|"delegates bot work"| node_handoffs
node_handoffs -->|"uses runtime state"| node_runtime_store
node_backend_entry -.->|"manages sessions"| node_runtime_store
node_runner -->|"loads capabilities"| node_skills_plugins
node_runner -->|"invokes tools"| node_mcp
node_runner -->|"uses workspace knowledge"| node_memory
node_backend_entry -.->|"supports durable goals"| node_goals
node_goals -.->|"tracks execution"| node_runtime_store
node_backend_entry -.->|"optionally dispatches"| node_cloud_runtime

click node_web "https://github.com/2sincejuly/skydot/blob/main/web/src/App.tsx"
click node_electron "https://github.com/2sincejuly/skydot/blob/main/electron/src/main/index.ts"
click node_auth "https://github.com/2sincejuly/skydot/blob/main/src/middleware/auth.ts"
click node_backend_entry "https://github.com/2sincejuly/skydot/blob/main/src/index.ts"
click node_database "https://github.com/2sincejuly/skydot/blob/main/src/db.ts"
click node_im_channels "https://github.com/2sincejuly/skydot/blob/main/src/im-manager.ts"
click node_tasks "https://github.com/2sincejuly/skydot/blob/main/src/task-scheduler.ts"
click node_runtime_store "https://github.com/2sincejuly/skydot/blob/main/src/personal-agent/product-runtime-store.ts"
click node_runner "https://github.com/2sincejuly/skydot/blob/main/container/agent-runner/src/index.ts"
click node_pi_runtime "https://github.com/2sincejuly/skydot/blob/main/container/agent-runner/src/runtime/pi/pi-runtime.ts"
click node_cloud_runtime "https://github.com/2sincejuly/skydot/blob/main/apps/cloud-agent/src/session-object.ts"
click node_groups "https://github.com/2sincejuly/skydot/blob/main/src/bot-groups/discussion-service.ts"
click node_handoffs "https://github.com/2sincejuly/skydot/blob/main/src/bot-groups/handoff-service.ts"
click node_skills_plugins "https://github.com/2sincejuly/skydot/blob/main/src/plugin-catalog.ts"
click node_mcp "https://github.com/2sincejuly/skydot/blob/main/src/mcp-client.ts"
click node_memory "https://github.com/2sincejuly/skydot/blob/main/src/memory-service.ts"
click node_goals "https://github.com/2sincejuly/skydot/blob/main/src/personal-agent/goal-runtime.ts"

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_web,node_electron,node_user toneBlue
class node_auth,node_backend_entry,node_database,node_im_channels,node_tasks,node_runtime_store toneAmber
class node_runner,node_pi_runtime,node_cloud_runtime toneMint
class node_groups,node_handoffs toneRose
class node_skills_plugins,node_mcp,node_memory,node_goals toneIndigo
```

## Components

### Clients

- [Web and PWA](https://github.com/2sincejuly/skydot/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Electron Desktop](https://github.com/2sincejuly/skydot/blob/main/electron/src/main/index.ts): `electron/src/main/index.ts`

### Backend Control Plane

- [Authentication and ACL](https://github.com/2sincejuly/skydot/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`
- [Backend Service](https://github.com/2sincejuly/skydot/blob/main/src/index.ts): `src/index.ts`
- [SQLite Persistence](https://github.com/2sincejuly/skydot/blob/main/src/db.ts): `src/db.ts`
- [Channel Connections](https://github.com/2sincejuly/skydot/blob/main/src/im-manager.ts): `src/im-manager.ts`
- [Task Scheduling](https://github.com/2sincejuly/skydot/blob/main/src/task-scheduler.ts): `src/task-scheduler.ts`
- [Product Runtime State](https://github.com/2sincejuly/skydot/blob/main/src/personal-agent/product-runtime-store.ts): `src/personal-agent/product-runtime-store.ts`

### Agent Execution

- [Agent Runner](https://github.com/2sincejuly/skydot/blob/main/container/agent-runner/src/index.ts): `container/agent-runner/src/index.ts`
- [Pi Runtime](https://github.com/2sincejuly/skydot/blob/main/container/agent-runner/src/runtime/pi/pi-runtime.ts): `container/agent-runner/src/runtime/pi/pi-runtime.ts`
- [Cloud Runtime](https://github.com/2sincejuly/skydot/blob/main/apps/cloud-agent/src/session-object.ts): `apps/cloud-agent/src/session-object.ts`

### Collaboration

- [Group Discussions](https://github.com/2sincejuly/skydot/blob/main/src/bot-groups/discussion-service.ts): `src/bot-groups/discussion-service.ts`
- [Bot Handoffs](https://github.com/2sincejuly/skydot/blob/main/src/bot-groups/handoff-service.ts): `src/bot-groups/handoff-service.ts`

### Work Capabilities

- [Skills and Plugins](https://github.com/2sincejuly/skydot/blob/main/src/plugin-catalog.ts): `src/plugin-catalog.ts`
- [MCP Integrations](https://github.com/2sincejuly/skydot/blob/main/src/mcp-client.ts): `src/mcp-client.ts`
- [Workspace Memory](https://github.com/2sincejuly/skydot/blob/main/src/memory-service.ts): `src/memory-service.ts`
- [Goals and Durable Work](https://github.com/2sincejuly/skydot/blob/main/src/personal-agent/goal-runtime.ts): `src/personal-agent/goal-runtime.ts`

### Other components

- **User**

## Connections

- User → Web and PWA: uses
- Web and PWA → Authentication and ACL: requests backend
- Electron Desktop → Web and PWA: shares frontend
- Authentication and ACL → Backend Service: guards access
- Backend Service → SQLite Persistence: persists state
- Backend Service → Agent Runner: dispatches execution
- Agent Runner → Pi Runtime: runs agent
- Backend Service → Channel Connections: connects channels
- Channel Connections → Backend Service: routes messages
- Backend Service → Task Scheduling: schedules work
- Task Scheduling → Agent Runner: starts runs
- Backend Service → Group Discussions: serves collaboration
- Group Discussions → Bot Handoffs: delegates bot work (evidence: `src/bot-groups/discussion-service.ts`)
- Bot Handoffs → Product Runtime State: uses runtime state (evidence: `src/bot-groups/handoff-service.ts`)
- Backend Service → Product Runtime State: manages sessions
- Agent Runner → Skills and Plugins: loads capabilities
- Agent Runner → MCP Integrations: invokes tools
- Agent Runner → Workspace Memory: uses workspace knowledge
- Backend Service → Goals and Durable Work: supports durable goals
- Goals and Durable Work → Product Runtime State: tracks execution
- Backend Service → Cloud Runtime: optionally dispatches
