# neuralnomadsai/codenomad architecture

> Architecture diagram of the GitHub repository neuralnomadsai/codenomad, 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/neuralnomadsai/codenomad
- Repository: https://github.com/neuralnomadsai/codenomad

## Overview

CodeNomad is a desktop and browser workspace for OpenCode V2. The main workflow is to open a project, connect to the shared OpenCode service, manage sessions, and work with conversation history and Git changes in the UI. The repository also documents remote access, files, previews, SideCars, plugins, speech, and desktop browser automation. The graph combines README-documented capabilities with relationships visible in the supplied excerpts and SOURCE INDEX; unsampled implementation details are not assumed.

Main entry points: [`packages/ui/src/App.tsx`](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/App.tsx) (Workspace App), [`packages/server/src/server/http-server.ts`](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/http-server.ts) (HTTP Server), [`packages/ui/src/stores/sessions.ts`](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/sessions.ts) (Session Store), [`packages/ui/src/lib/api-client.ts`](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/api-client.ts) (HTTP API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workspace UI"]
  node_app["Workspace App<br/>[App.tsx]"]
  node_prompt["Prompt Composer<br/>[prompt-input.tsx]"]
  node_conversation["Conversation View<br/>[session-view.tsx]"]
  node_rightpanel["Workspace Panels"]
  node_apiclient["HTTP API Client<br/>[api-client.ts]"]
  node_storageui["Storage Cache<br/>[storage.ts]"]
  node_uilog["UI Logging<br/>[logger.ts]"]
end

subgraph group_session["Sessions and Git"]
  node_sessionui["Session Store<br/>[sessions.ts]"]
  node_sessionapi["Session API<br/>[session-api.ts]"]
  node_sessionstate["Session State<br/>[session-state.ts]"]
  node_history["History Navigation"]
  node_worktrees["Git Worktrees<br/>[worktrees.ts]"]
end

subgraph group_server["Server Services"]
  node_server["HTTP Server<br/>[http-server.ts]"]
  node_workspace["Workspace Manager<br/>[manager.ts]"]
  node_opencode["OpenCode Service"]
  node_events["Event Bus<br/>[bus.ts]"]
  node_storage[("Instance Storage<br/>[instance-store.ts]")]
  node_filesystem["File Access<br/>[filesystem.ts]"]
  node_types["Shared Contracts<br/>[api-types.ts]"]
end

subgraph group_desktop["Desktop Runtime"]
  node_desktop["Desktop Host<br/>[main.ts]"]
end

subgraph group_integrations["Tools and Access"]
  node_browserpreview["Browser Preview"]
  node_remote["Remote Access<br/>[manager.ts]"]
  node_sidecars["SideCars<br/>[manager.ts]"]
  node_plugins["Plugin Controls<br/>[plugin-controls.ts]"]
  node_speech["Speech<br/>[service.ts]"]
end

node_developer(("Developer"))

node_developer -->|"opens workspace"| node_app
node_app -->|"composes prompts"| node_prompt
node_app -->|"browses sessions"| node_sessionui
node_sessionui -->|"loads sessions"| node_sessionapi
node_sessionui -->|"reloads worktrees"| node_worktrees
node_sessionui -->|"uses state"| node_sessionstate
node_sessionui -->|"shows conversation"| node_conversation
node_sessionapi -.->|"requests data"| node_apiclient
node_conversation -->|"navigates history"| node_history
node_app -->|"shows Git changes"| node_rightpanel
node_worktrees -.->|"manages worktrees"| node_workspace
node_apiclient -->|"sends requests"| node_server
node_server -.->|"routes workspace operations"| node_workspace
node_workspace -->|"connects service"| node_opencode
node_server -.->|"serves file access"| node_filesystem
node_server -->|"reads and writes"| node_storage
node_storageui -->|"loads and patches"| node_apiclient
node_storageui -->|"updates cache"| node_events
node_server -->|"publishes events"| node_events
node_server -->|"uses contracts"| node_types
node_developer -->|"runs desktop app"| node_desktop
node_desktop -->|"hosts previews"| node_browserpreview
node_developer -->|"authenticates remotely"| node_remote
node_app -->|"opens web tools"| node_sidecars
node_app -->|"manages activation"| node_plugins
node_prompt -->|"uses voice input"| node_speech
node_app -.->|"logs UI activity"| node_uilog

click node_app "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/App.tsx"
click node_prompt "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/components/prompt-input.tsx"
click node_conversation "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/components/session/session-view.tsx"
click node_sessionui "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/sessions.ts"
click node_sessionapi "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/session-api.ts"
click node_sessionstate "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/session-state.ts"
click node_history "https://github.com/neuralnomadsai/codenomad/tree/dev/packages/server/src/opencode/session-pruning"
click node_worktrees "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/worktrees.ts"
click node_rightpanel "https://github.com/neuralnomadsai/codenomad/tree/dev/packages/ui/src/components/instance/shell/right-panel"
click node_apiclient "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/api-client.ts"
click node_server "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/http-server.ts"
click node_workspace "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/workspaces/manager.ts"
click node_opencode "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/workspaces/opencode-service.ts"
click node_events "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/events/bus.ts"
click node_storage "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/storage/instance-store.ts"
click node_storageui "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/storage.ts"
click node_desktop "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/electron-app/electron/main/main.ts"
click node_browserpreview "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/electron-app/electron/main/browser-controller.ts"
click node_remote "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/auth/manager.ts"
click node_sidecars "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/sidecars/manager.ts"
click node_plugins "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/routes/plugin-controls.ts"
click node_speech "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/speech/service.ts"
click node_filesystem "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/routes/filesystem.ts"
click node_types "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/api-types.ts"
click node_uilog "https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/logger.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_app,node_prompt,node_conversation,node_rightpanel,node_apiclient,node_storageui,node_uilog toneBlue
class node_sessionui,node_sessionapi,node_sessionstate,node_history,node_worktrees toneAmber
class node_server,node_workspace,node_opencode,node_events,node_storage,node_filesystem,node_types toneMint
class node_desktop toneRose
class node_browserpreview,node_remote,node_sidecars,node_plugins,node_speech,node_developer toneIndigo
```

## Components

### Workspace UI

- [Workspace App](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/App.tsx): `packages/ui/src/App.tsx`
- [Prompt Composer](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/components/prompt-input.tsx): `packages/ui/src/components/prompt-input.tsx`
- [Conversation View](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/components/session/session-view.tsx): `packages/ui/src/components/session/session-view.tsx`
- [Workspace Panels](https://github.com/neuralnomadsai/codenomad/tree/dev/packages/ui/src/components/instance/shell/right-panel): `packages/ui/src/components/instance/shell/right-panel`
- [HTTP API Client](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/api-client.ts): `packages/ui/src/lib/api-client.ts`
- [Storage Cache](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/storage.ts): `packages/ui/src/lib/storage.ts`
- [UI Logging](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/lib/logger.ts): `packages/ui/src/lib/logger.ts`

### Sessions and Git

- [Session Store](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/sessions.ts): `packages/ui/src/stores/sessions.ts`
- [Session API](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/session-api.ts): `packages/ui/src/stores/session-api.ts`
- [Session State](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/session-state.ts): `packages/ui/src/stores/session-state.ts`
- [History Navigation](https://github.com/neuralnomadsai/codenomad/tree/dev/packages/server/src/opencode/session-pruning): `packages/server/src/opencode/session-pruning`
- [Git Worktrees](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/ui/src/stores/worktrees.ts): `packages/ui/src/stores/worktrees.ts`

### Server Services

- [HTTP Server](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/http-server.ts): `packages/server/src/server/http-server.ts`
- [Workspace Manager](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/workspaces/manager.ts): `packages/server/src/workspaces/manager.ts`
- [OpenCode Service](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/workspaces/opencode-service.ts): `packages/server/src/workspaces/opencode-service.ts`
- [Event Bus](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/events/bus.ts): `packages/server/src/events/bus.ts`
- [Instance Storage](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/storage/instance-store.ts): `packages/server/src/storage/instance-store.ts`
- [File Access](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/routes/filesystem.ts): `packages/server/src/server/routes/filesystem.ts`
- [Shared Contracts](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/api-types.ts): `packages/server/src/api-types.ts`

### Desktop Runtime

- [Desktop Host](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/electron-app/electron/main/main.ts): `packages/electron-app/electron/main/main.ts`

### Tools and Access

- [Browser Preview](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/electron-app/electron/main/browser-controller.ts): `packages/electron-app/electron/main/browser-controller.ts`
- [Remote Access](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/auth/manager.ts): `packages/server/src/auth/manager.ts`
- [SideCars](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/sidecars/manager.ts): `packages/server/src/sidecars/manager.ts`
- [Plugin Controls](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/server/routes/plugin-controls.ts): `packages/server/src/server/routes/plugin-controls.ts`
- [Speech](https://github.com/neuralnomadsai/codenomad/blob/dev/packages/server/src/speech/service.ts): `packages/server/src/speech/service.ts`

### Other components

- **Developer**

## Connections

- Developer → Workspace App: opens workspace (evidence: `README.md`)
- Workspace App → Prompt Composer: composes prompts (evidence: `README.md`)
- Workspace App → Session Store: browses sessions (evidence: `README.md`)
- Session Store → Session API: loads sessions (evidence: `packages/ui/src/stores/sessions.ts`)
- Session Store → Git Worktrees: reloads worktrees (evidence: `packages/ui/src/stores/sessions.ts`)
- Session Store → Session State: uses state (evidence: `packages/ui/src/stores/sessions.ts`)
- Session Store → Conversation View: shows conversation (evidence: `README.md`)
- Session API → HTTP API Client: requests data
- Conversation View → History Navigation: navigates history (evidence: `README.md`)
- Workspace App → Workspace Panels: shows Git changes (evidence: `README.md`)
- Git Worktrees → Workspace Manager: manages worktrees
- HTTP API Client → HTTP Server: sends requests (evidence: `packages/ui/src/lib/api-client.ts`)
- HTTP Server → Workspace Manager: routes workspace operations
- Workspace Manager → OpenCode Service: connects service (evidence: `README.md`)
- HTTP Server → File Access: serves file access
- HTTP Server → Instance Storage: reads and writes
- Storage Cache → HTTP API Client: loads and patches (evidence: `packages/ui/src/lib/storage.ts`)
- Storage Cache → Event Bus: updates cache (evidence: `packages/ui/src/lib/storage.ts`)
- HTTP Server → Event Bus: publishes events
- HTTP Server → Shared Contracts: uses contracts
- Developer → Desktop Host: runs desktop app (evidence: `README.md`)
- Desktop Host → Browser Preview: hosts previews (evidence: `README.md`)
- Developer → Remote Access: authenticates remotely (evidence: `README.md`)
- Workspace App → SideCars: opens web tools (evidence: `README.md`)
- Workspace App → Plugin Controls: manages activation (evidence: `README.md`)
- Prompt Composer → Speech: uses voice input (evidence: `README.md`)
- Workspace App → UI Logging: logs UI activity (evidence: `packages/ui/src/App.tsx`)
