# jasonkneen/agensis architecture

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

- Interactive diagram: https://gitdiagram.com/jasonkneen/agensis
- Repository: https://github.com/jasonkneen/agensis
- Video tour (about a minute): https://gitdiagram.com/jasonkneen/agensis/video

## Overview

agensis is a collaborative workspace where people and AI agents share conversations, tasks, memory, documents, files, and a canvas. The principal workflow is working in a workspace conversation, assigning or triggering agent work, and receiving responses and updates; tasks, automations, and external bridges extend that workflow. The README documents these capabilities and the two-backend deployment, while sampled source confirms task persistence/realtime subscriptions, inference relaying, and desktop runtime features. Many feature-specific route implementations were not sampled, so their internal wiring is left unspecified.

Main entry points: [`server/index.cjs`](https://github.com/jasonkneen/agensis/blob/main/server/index.cjs) (Node API and WS), [`src/lib/backendClient.ts`](https://github.com/jasonkneen/agensis/blob/main/src/lib/backendClient.ts) (Backend client), [`src/hooks/useTasks.ts`](https://github.com/jasonkneen/agensis/blob/main/src/hooks/useTasks.ts) (Task state), [`netlify/functions/backend.mjs`](https://github.com/jasonkneen/agensis/blob/main/netlify/functions/backend.mjs) (Serverless HTTP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workspace client"]
  node_web["Workspace app<br/>[App.tsx]"]
  node_taskui["Tasks UI"]
  node_taskhook["Task state<br/>[useTasks.ts]"]
  node_backendclient["Backend client<br/>[backendClient.ts]"]
  node_realtimeclient["Realtime manager<br/>[realtimeManager.ts]"]
end

subgraph group_backend["Backend services"]
  node_nodebackend["Node API and WS<br/>[index.cjs]"]
  node_httpbackend["Serverless HTTP<br/>[backend.mjs]"]
  node_sharedrules["Shared backend rules<br/>[backend-core.cjs]"]
end

subgraph group_agents["Agent runtime"]
  node_agentroutes["Agent endpoints<br/>[agents-routes.cjs]"]
  node_agentjobs["Agent jobs<br/>[agent-jobs.cjs]"]
  node_dispatch["Task dispatch<br/>[task-dispatch.cjs]"]
  node_inference["Shared-model inference"]
end

subgraph group_collaboration["Collaboration features"]
  node_chat["Conversation and channels<br/>[ai-chat-routes.cjs]"]
  node_automations["Automations<br/>[automations.cjs]"]
  node_bridges["Channel bridges"]
  node_huddles["Voice huddles<br/>[huddles.cjs]"]
end

subgraph group_desktop["Desktop runtime"]
  node_desktop["Electron shell<br/>[main.cjs]"]
  node_localruntime["Local runtime supervisor<br/>[supervisor.cjs]"]
  node_broadcast["Stream capture engine<br/>[engine.cjs]"]
end

node_person(("Workspace user"))
node_postgres[("Postgres")]
node_daemon(("Linked agent daemon"))

node_person -->|"uses"| node_web
node_web -->|"requests"| node_backendclient
node_taskui -->|"manages tasks"| node_taskhook
node_taskhook -->|"reads and writes"| node_backendclient
node_taskhook -->|"subscribes"| node_realtimeclient
node_realtimeclient -->|"creates channels"| node_backendclient
node_backendclient -->|"API and realtime"| node_nodebackend
node_backendclient -.->|"HTTP requests"| node_httpbackend
node_nodebackend -->|"uses rules"| node_sharedrules
node_httpbackend -->|"uses rules"| node_sharedrules
node_nodebackend -->|"reads and writes"| node_postgres
node_httpbackend -->|"reads and writes"| node_postgres
node_daemon -->|"opens WebSocket"| node_nodebackend
node_nodebackend -->|"mounts endpoints"| node_agentroutes
node_nodebackend -->|"mounts endpoints"| node_agentjobs
node_nodebackend -->|"dispatches work"| node_dispatch
node_nodebackend -->|"mounts routes"| node_inference
node_inference -->|"relays inference"| node_daemon
node_nodebackend -->|"mounts routes"| node_chat
node_nodebackend -->|"loads automation"| node_automations
node_nodebackend -->|"loads bridges"| node_bridges
node_nodebackend -->|"loads huddles"| node_huddles
node_desktop -->|"supervises agents"| node_localruntime
node_desktop -->|"controls streaming"| node_broadcast

click node_web "https://github.com/jasonkneen/agensis/blob/main/src/App.tsx"
click node_taskui "https://github.com/jasonkneen/agensis/blob/main/src/components/windows/TasksWindowContent.tsx"
click node_taskhook "https://github.com/jasonkneen/agensis/blob/main/src/hooks/useTasks.ts"
click node_backendclient "https://github.com/jasonkneen/agensis/blob/main/src/lib/backendClient.ts"
click node_realtimeclient "https://github.com/jasonkneen/agensis/blob/main/src/lib/realtimeManager.ts"
click node_nodebackend "https://github.com/jasonkneen/agensis/blob/main/server/index.cjs"
click node_httpbackend "https://github.com/jasonkneen/agensis/blob/main/netlify/functions/backend.mjs"
click node_sharedrules "https://github.com/jasonkneen/agensis/blob/main/shared/backend-core.cjs"
click node_agentroutes "https://github.com/jasonkneen/agensis/blob/main/server/agents-routes.cjs"
click node_agentjobs "https://github.com/jasonkneen/agensis/blob/main/server/agent-jobs.cjs"
click node_dispatch "https://github.com/jasonkneen/agensis/blob/main/server/task-dispatch.cjs"
click node_inference "https://github.com/jasonkneen/agensis/blob/main/server/inference-routes.cjs"
click node_chat "https://github.com/jasonkneen/agensis/blob/main/server/ai-chat-routes.cjs"
click node_automations "https://github.com/jasonkneen/agensis/blob/main/server/automations.cjs"
click node_bridges "https://github.com/jasonkneen/agensis/blob/main/server/channel-bridges.cjs"
click node_huddles "https://github.com/jasonkneen/agensis/blob/main/server/huddles.cjs"
click node_desktop "https://github.com/jasonkneen/agensis/blob/main/electron/main.cjs"
click node_localruntime "https://github.com/jasonkneen/agensis/blob/main/electron/local-runtime/supervisor.cjs"
click node_broadcast "https://github.com/jasonkneen/agensis/blob/main/electron/broadcast/engine.cjs"

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_taskui,node_taskhook,node_backendclient,node_realtimeclient,node_person toneBlue
class node_nodebackend,node_httpbackend,node_sharedrules,node_postgres toneAmber
class node_agentroutes,node_agentjobs,node_dispatch,node_inference toneMint
class node_chat,node_automations,node_bridges,node_huddles toneRose
class node_desktop,node_localruntime,node_broadcast,node_daemon toneIndigo
```

## Components

### Workspace client

- [Workspace app](https://github.com/jasonkneen/agensis/blob/main/src/App.tsx): `src/App.tsx`
- [Tasks UI](https://github.com/jasonkneen/agensis/blob/main/src/components/windows/TasksWindowContent.tsx): `src/components/windows/TasksWindowContent.tsx`
- [Task state](https://github.com/jasonkneen/agensis/blob/main/src/hooks/useTasks.ts): `src/hooks/useTasks.ts`
- [Backend client](https://github.com/jasonkneen/agensis/blob/main/src/lib/backendClient.ts): `src/lib/backendClient.ts`
- [Realtime manager](https://github.com/jasonkneen/agensis/blob/main/src/lib/realtimeManager.ts): `src/lib/realtimeManager.ts`

### Backend services

- [Node API and WS](https://github.com/jasonkneen/agensis/blob/main/server/index.cjs): `server/index.cjs`
- [Serverless HTTP](https://github.com/jasonkneen/agensis/blob/main/netlify/functions/backend.mjs): `netlify/functions/backend.mjs`
- [Shared backend rules](https://github.com/jasonkneen/agensis/blob/main/shared/backend-core.cjs): `shared/backend-core.cjs`

### Agent runtime

- [Agent endpoints](https://github.com/jasonkneen/agensis/blob/main/server/agents-routes.cjs): `server/agents-routes.cjs`
- [Agent jobs](https://github.com/jasonkneen/agensis/blob/main/server/agent-jobs.cjs): `server/agent-jobs.cjs`
- [Task dispatch](https://github.com/jasonkneen/agensis/blob/main/server/task-dispatch.cjs): `server/task-dispatch.cjs`
- [Shared-model inference](https://github.com/jasonkneen/agensis/blob/main/server/inference-routes.cjs): `server/inference-routes.cjs`

### Collaboration features

- [Conversation and channels](https://github.com/jasonkneen/agensis/blob/main/server/ai-chat-routes.cjs): `server/ai-chat-routes.cjs`
- [Automations](https://github.com/jasonkneen/agensis/blob/main/server/automations.cjs): `server/automations.cjs`
- [Channel bridges](https://github.com/jasonkneen/agensis/blob/main/server/channel-bridges.cjs): `server/channel-bridges.cjs`
- [Voice huddles](https://github.com/jasonkneen/agensis/blob/main/server/huddles.cjs): `server/huddles.cjs`

### Desktop runtime

- [Electron shell](https://github.com/jasonkneen/agensis/blob/main/electron/main.cjs): `electron/main.cjs`
- [Local runtime supervisor](https://github.com/jasonkneen/agensis/blob/main/electron/local-runtime/supervisor.cjs): `electron/local-runtime/supervisor.cjs`
- [Stream capture engine](https://github.com/jasonkneen/agensis/blob/main/electron/broadcast/engine.cjs): `electron/broadcast/engine.cjs`

### Other components

- **Workspace user**
- **Postgres**
- **Linked agent daemon**

## Connections

- Workspace user → Workspace app: uses
- Workspace app → Backend client: requests
- Tasks UI → Task state: manages tasks
- Task state → Backend client: reads and writes
- Task state → Realtime manager: subscribes
- Realtime manager → Backend client: creates channels
- Backend client → Node API and WS: API and realtime
- Backend client → Serverless HTTP: HTTP requests
- Node API and WS → Shared backend rules: uses rules
- Serverless HTTP → Shared backend rules: uses rules
- Node API and WS → Postgres: reads and writes
- Serverless HTTP → Postgres: reads and writes
- Linked agent daemon → Node API and WS: opens WebSocket
- Node API and WS → Agent endpoints: mounts endpoints
- Node API and WS → Agent jobs: mounts endpoints
- Node API and WS → Task dispatch: dispatches work
- Node API and WS → Shared-model inference: mounts routes
- Shared-model inference → Linked agent daemon: relays inference
- Node API and WS → Conversation and channels: mounts routes
- Node API and WS → Automations: loads automation
- Node API and WS → Channel bridges: loads bridges
- Node API and WS → Voice huddles: loads huddles
- Electron shell → Local runtime supervisor: supervises agents
- Electron shell → Stream capture engine: controls streaming