# tim5wang/godex architecture

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

- Interactive diagram: https://gitdiagram.com/tim5wang/godex
- Repository: https://github.com/tim5wang/godex

## Overview

GoDex is a local-first AI agent workspace whose entry points share session and execution capabilities. A typical user submits a chat through the Web workspace or another channel; the backend manages a session and agent turn, which can call model providers and governed tools, then returns results to the session timeline. Distinct product branches include long-running task and subagent orchestration, memory and history, automation, and workspace management. The README documents broad capability sharing; sampled source confirms selected route, persistence, and configuration behavior, but not every runtime connection.

Main entry points: [`internal/agent/runtime.go`](https://github.com/tim5wang/godex/blob/main/internal/agent/runtime.go) (Agent runtime), [`internal/services/backend/backend.go`](https://github.com/tim5wang/godex/blob/main/internal/services/backend/backend.go) (Backend service), [`internal/runtime/httpapi/httpapi.go`](https://github.com/tim5wang/godex/blob/main/internal/runtime/httpapi/httpapi.go) (HTTP API), [`internal/core/conversation/runner.go`](https://github.com/tim5wang/godex/blob/main/internal/core/conversation/runner.go) (Conversation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry surfaces"]
  node_web["Web workspace<br/>[App.tsx]"]
  node_cli["CLI / TUI<br/>[main.go]"]
  node_channels["IM channels<br/>[channels.go]"]
  node_http["HTTP API<br/>[httpapi.go]"]
end

subgraph group_execution["Agent execution"]
  node_backend["Backend service<br/>[backend.go]"]
  node_agent["Agent runtime<br/>[runtime.go]"]
  node_conversation["Conversation engine<br/>[runner.go]"]
  node_providers["Model providers<br/>[providers.go]"]
  node_toolruntime["Tool execution<br/>[runtime.go]"]
  node_safety["Permissions &amp; safety<br/>[permissions.go]"]
  node_longtask["Long tasks<br/>[longtask.go]"]
  node_subagents["Subagents &amp; workflows<br/>[subagent_run.go]"]
end

subgraph group_workspace["Workspace capabilities"]
  node_files["Workspace files<br/>[workspacefs.go]"]
  node_notes[("Notes<br/>[notes.go]")]
  node_skills["Skills &amp; packages<br/>[packages.go]"]
  node_templates["Agent templates<br/>[manager.go]"]
end

subgraph group_platform["Runtime platform"]
  node_sessions[("Session state<br/>[store.go]")]
  node_memory[("Memory &amp; recall<br/>[manager.go]")]
  node_history["History search<br/>[service.go]"]
  node_config[("Configuration<br/>[manager.go]")]
end

subgraph group_operations["Operations"]
  node_automation["Cron &amp; heartbeat<br/>[service.go]"]
  node_nodes[("Node registry &amp; relay<br/>[registry.go]")]
  node_usage[("Usage tracking<br/>[service.go]")]
  node_plugins["Plugin runtime<br/>[manager.go]"]
  node_taskboard["Taskboard<br/>[routes.go]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_cli
node_user -->|"messages"| node_channels
node_web -->|"requests"| node_http
node_cli -->|"submits turns"| node_backend
node_channels -->|"shares sessions"| node_backend
node_http -->|"serves operations"| node_backend
node_backend -->|"runs turns"| node_agent
node_agent -->|"executes dialogue"| node_conversation
node_conversation -->|"requests completions"| node_providers
node_agent -->|"dispatches tools"| node_toolruntime
node_toolruntime -->|"checks permissions"| node_safety
node_agent -->|"persists session"| node_sessions
node_agent -->|"uses memory"| node_memory
node_backend -->|"searches history"| node_history
node_agent -->|"runs long tasks"| node_longtask
node_agent -->|"delegates work"| node_subagents
node_agent -->|"works in workspace"| node_files
node_agent -->|"uses profiles"| node_templates
node_agent -->|"uses capabilities"| node_skills
node_backend -->|"manages notes"| node_notes
node_automation -->|"triggers work"| node_backend
node_backend -->|"observes nodes"| node_nodes
node_conversation -->|"records usage"| node_usage
node_backend -->|"manages plugins"| node_plugins
node_taskboard -->|"dispatches execution"| node_backend
node_http -->|"updates settings"| node_config

click node_web "https://github.com/tim5wang/godex/blob/main/ui/web/src/App.tsx"
click node_cli "https://github.com/tim5wang/godex/blob/main/cmd/godex/main.go"
click node_channels "https://github.com/tim5wang/godex/blob/main/internal/runtime/channels/channels.go"
click node_http "https://github.com/tim5wang/godex/blob/main/internal/runtime/httpapi/httpapi.go"
click node_backend "https://github.com/tim5wang/godex/blob/main/internal/services/backend/backend.go"
click node_agent "https://github.com/tim5wang/godex/blob/main/internal/agent/runtime.go"
click node_conversation "https://github.com/tim5wang/godex/blob/main/internal/core/conversation/runner.go"
click node_providers "https://github.com/tim5wang/godex/blob/main/internal/core/providers/providers.go"
click node_toolruntime "https://github.com/tim5wang/godex/blob/main/internal/toolruntime/runtime.go"
click node_safety "https://github.com/tim5wang/godex/blob/main/internal/toolruntime/permissions.go"
click node_longtask "https://github.com/tim5wang/godex/blob/main/internal/agent/longtask.go"
click node_subagents "https://github.com/tim5wang/godex/blob/main/internal/agent/subagent_run.go"
click node_sessions "https://github.com/tim5wang/godex/blob/main/internal/sessionstore/store.go"
click node_memory "https://github.com/tim5wang/godex/blob/main/internal/core/memory/manager.go"
click node_history "https://github.com/tim5wang/godex/blob/main/internal/services/historysearch/service.go"
click node_config "https://github.com/tim5wang/godex/blob/main/internal/core/config/manager.go"
click node_files "https://github.com/tim5wang/godex/blob/main/internal/platform/workspacefs/workspacefs.go"
click node_notes "https://github.com/tim5wang/godex/blob/main/internal/core/notes/notes.go"
click node_skills "https://github.com/tim5wang/godex/blob/main/internal/core/packages/packages.go"
click node_templates "https://github.com/tim5wang/godex/blob/main/internal/core/templates/manager.go"
click node_automation "https://github.com/tim5wang/godex/blob/main/internal/runtime/cron/service.go"
click node_nodes "https://github.com/tim5wang/godex/blob/main/internal/services/noderegistry/registry.go"
click node_usage "https://github.com/tim5wang/godex/blob/main/internal/services/usage/service.go"
click node_plugins "https://github.com/tim5wang/godex/blob/main/internal/pluginrt/manager.go"
click node_taskboard "https://github.com/tim5wang/godex/blob/main/internal/plugins/taskboard/routes.go"

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_cli,node_channels,node_http,node_user toneBlue
class node_backend,node_agent,node_conversation,node_providers,node_toolruntime,node_safety,node_longtask,node_subagents toneAmber
class node_files,node_notes,node_skills,node_templates toneMint
class node_sessions,node_memory,node_history,node_config toneRose
class node_automation,node_nodes,node_usage,node_plugins,node_taskboard toneIndigo
```

## Components

### Entry surfaces

- [Web workspace](https://github.com/tim5wang/godex/blob/main/ui/web/src/App.tsx): `ui/web/src/App.tsx`
- [CLI / TUI](https://github.com/tim5wang/godex/blob/main/cmd/godex/main.go): `cmd/godex/main.go`
- [IM channels](https://github.com/tim5wang/godex/blob/main/internal/runtime/channels/channels.go): `internal/runtime/channels/channels.go`
- [HTTP API](https://github.com/tim5wang/godex/blob/main/internal/runtime/httpapi/httpapi.go): `internal/runtime/httpapi/httpapi.go`

### Agent execution

- [Backend service](https://github.com/tim5wang/godex/blob/main/internal/services/backend/backend.go): `internal/services/backend/backend.go`
- [Agent runtime](https://github.com/tim5wang/godex/blob/main/internal/agent/runtime.go): `internal/agent/runtime.go`
- [Conversation engine](https://github.com/tim5wang/godex/blob/main/internal/core/conversation/runner.go): `internal/core/conversation/runner.go`
- [Model providers](https://github.com/tim5wang/godex/blob/main/internal/core/providers/providers.go): `internal/core/providers/providers.go`
- [Tool execution](https://github.com/tim5wang/godex/blob/main/internal/toolruntime/runtime.go): `internal/toolruntime/runtime.go`
- [Permissions & safety](https://github.com/tim5wang/godex/blob/main/internal/toolruntime/permissions.go): `internal/toolruntime/permissions.go`
- [Long tasks](https://github.com/tim5wang/godex/blob/main/internal/agent/longtask.go): `internal/agent/longtask.go`
- [Subagents & workflows](https://github.com/tim5wang/godex/blob/main/internal/agent/subagent_run.go): `internal/agent/subagent_run.go`

### Workspace capabilities

- [Workspace files](https://github.com/tim5wang/godex/blob/main/internal/platform/workspacefs/workspacefs.go): `internal/platform/workspacefs/workspacefs.go`
- [Notes](https://github.com/tim5wang/godex/blob/main/internal/core/notes/notes.go): `internal/core/notes/notes.go`
- [Skills & packages](https://github.com/tim5wang/godex/blob/main/internal/core/packages/packages.go): `internal/core/packages/packages.go`
- [Agent templates](https://github.com/tim5wang/godex/blob/main/internal/core/templates/manager.go): `internal/core/templates/manager.go`

### Runtime platform

- [Session state](https://github.com/tim5wang/godex/blob/main/internal/sessionstore/store.go): `internal/sessionstore/store.go`
- [Memory & recall](https://github.com/tim5wang/godex/blob/main/internal/core/memory/manager.go): `internal/core/memory/manager.go`
- [History search](https://github.com/tim5wang/godex/blob/main/internal/services/historysearch/service.go): `internal/services/historysearch/service.go`
- [Configuration](https://github.com/tim5wang/godex/blob/main/internal/core/config/manager.go): `internal/core/config/manager.go`

### Operations

- [Cron & heartbeat](https://github.com/tim5wang/godex/blob/main/internal/runtime/cron/service.go): `internal/runtime/cron/service.go`
- [Node registry & relay](https://github.com/tim5wang/godex/blob/main/internal/services/noderegistry/registry.go): `internal/services/noderegistry/registry.go`
- [Usage tracking](https://github.com/tim5wang/godex/blob/main/internal/services/usage/service.go): `internal/services/usage/service.go`
- [Plugin runtime](https://github.com/tim5wang/godex/blob/main/internal/pluginrt/manager.go): `internal/pluginrt/manager.go`
- [Taskboard](https://github.com/tim5wang/godex/blob/main/internal/plugins/taskboard/routes.go): `internal/plugins/taskboard/routes.go`

### Other components

- **User**

## Connections

- User → Web workspace: uses
- User → CLI / TUI: uses
- User → IM channels: messages
- Web workspace → HTTP API: requests
- CLI / TUI → Backend service: submits turns
- IM channels → Backend service: shares sessions
- HTTP API → Backend service: serves operations
- Backend service → Agent runtime: runs turns
- Agent runtime → Conversation engine: executes dialogue
- Conversation engine → Model providers: requests completions
- Agent runtime → Tool execution: dispatches tools
- Tool execution → Permissions & safety: checks permissions
- Agent runtime → Session state: persists session
- Agent runtime → Memory & recall: uses memory
- Backend service → History search: searches history
- Agent runtime → Long tasks: runs long tasks
- Agent runtime → Subagents & workflows: delegates work
- Agent runtime → Workspace files: works in workspace
- Agent runtime → Agent templates: uses profiles
- Agent runtime → Skills & packages: uses capabilities
- Backend service → Notes: manages notes
- Cron & heartbeat → Backend service: triggers work
- Backend service → Node registry & relay: observes nodes
- Conversation engine → Usage tracking: records usage
- Backend service → Plugin runtime: manages plugins
- Taskboard → Backend service: dispatches execution
- HTTP API → Configuration: updates settings