NomadArch/dev-docs/architecture.md

CodeNomad Architecture

Overview

CodeNomad is a cross-platform desktop application built with Electron that provides a multi-instance, multi-session interface for interacting with OpenCode servers. Each instance manages its own OpenCode server process and can handle multiple concurrent sessions.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    Electron Main Process                │
│  - Window management                                    │
│  - Process spawning (opencode serve)                    │
│  - IPC bridge to renderer                               │
│  - File system operations                               │
└────────────────┬────────────────────────────────────────┘
                 │ IPC
┌────────────────┴────────────────────────────────────────┐
│                  Electron Renderer Process              │
│  ┌──────────────────────────────────────────────────┐  │
│  │              SolidJS Application                 │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │  Instance Manager                          │  │  │
│  │  │  - Spawns/kills OpenCode servers           │  │  │
│  │  │  - Manages SDK clients per instance        │  │  │
│  │  │  - Handles port allocation                 │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │  State Management (SolidJS Stores)         │  │  │
│  │  │  - instances[]                             │  │  │
│  │  │  - sessions[] per instance                 │  │  │
│  │  │  - normalized message store per session    │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │  UI Components                             │  │  │
│  │  │  - InstanceTabs                            │  │  │
│  │  │  - SessionTabs                             │  │  │
│  │  │  - MessageSection                        │  │  │
│  │  │  - PromptInput                             │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                 │ HTTP/SSE
┌────────────────┴────────────────────────────────────────┐
│           Multiple OpenCode Server Processes            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Instance 1   │  │ Instance 2   │  │ Instance 3   │  │
│  │ Port: 4096   │  │ Port: 4097   │  │ Port: 4098   │  │
│  │ ~/project-a  │  │ ~/project-a  │  │ ~/api        │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘

Component Layers

1. Main Process Layer (Electron)

Responsibilities:

• Create and manage application window
• Spawn OpenCode server processes as child processes
• Parse server stdout to extract port information
• Handle process lifecycle (start, stop, restart)
• Provide IPC handlers for renderer requests
• Manage native OS integrations (file dialogs, menus)

Key Modules:

• main.ts - Application entry point
• process-manager.ts - OpenCode server process spawning
• ipc-handlers.ts - IPC communication handlers
• menu.ts - Native application menu

2. Renderer Process Layer (SolidJS)

Responsibilities:

• Render UI components
• Manage application state
• Handle user interactions
• Communicate with OpenCode servers via HTTP/SSE
• Real-time message streaming

Key Modules:

• App.tsx - Root component
• stores/ - State management
• components/ - UI components
• contexts/ - SolidJS context providers
• lib/ - Utilities and helpers

3. Communication Layer

HTTP API Communication:

• SDK client per instance
• RESTful API calls for session/config/file operations
• Error handling and retries

SSE (Server-Sent Events):

• One EventSource per instance
• Real-time message updates
• Event type routing
• Reconnection logic

CLI Proxy Paths:

• The CLI server terminates all HTTP/SSE traffic and forwards it to the correct OpenCode instance.
• Each WorkspaceDescriptor exposes proxyPath (e.g., /workspaces/<id>/instance), which acts as the base URL for both REST and SSE calls.
• The renderer never touches the random per-instance port directly; it only talks to window.location.origin + proxyPath so a single CLI port can front every session.

Data Flow

Instance Creation Flow

1. User selects folder via Electron file dialog
2. Main process receives folder path via IPC
3. Main process spawns opencode serve --port 0
4. Main process parses stdout for port number
5. Main process sends port + PID back to renderer
6. Renderer creates SDK client for that port
7. Renderer fetches initial session list
8. Renderer displays session picker

Message Streaming Flow

1. User submits prompt in active session
2. Renderer POSTs to /session/:id/message
3. SSE connection receives MessageUpdated events
4. Events are routed to correct instance → session
5. Message state updates trigger UI re-render
6. Messages display with auto-scroll

Child Session Creation Flow

1. OpenCode server creates child session
2. SSE emits SessionUpdated event with parentId
3. Renderer adds session to instance's session list
4. New session tab appears automatically
5. Optional: Auto-switch to new tab

State Management

Instance State

instances: Map<instanceId, {
  id: string
  folder: string
  port: number
  pid: number
  proxyPath: string // `/workspaces/:id/instance`
  status: 'starting' | 'ready' | 'error' | 'stopped'
  client: OpenCodeClient
  eventSource: EventSource
  sessions: Map<sessionId, Session>
  activeSessionId: string | null
  logs: string[]
}>

Session State

Session: {
  id: string
  title: string
  parentId: string | null
  messages: Message[]
  agent: string
  model: { providerId: string, modelId: string }
  status: 'idle' | 'streaming' | 'error'
}

Message State

Message: {
  id: string
  sessionId: string
  type: 'user' | 'assistant'
  parts: Part[]
  timestamp: number
  status: 'sending' | 'sent' | 'streaming' | 'complete' | 'error'
}

Tab Hierarchy

Level 1: Instance Tabs

Each tab represents one OpenCode server instance:

• Label: Folder name (with counter if duplicate)
• Icon: Folder icon
• Close button: Stops server and closes tab
• "+" button: Opens folder picker for new instance

Level 2: Session Tabs

Each instance has multiple session tabs:

• Main session tab (always present)
• Child session tabs (auto-created)
• Logs tab (shows server output)
• "+" button: Creates new session

Tab Behavior

Instance Tab Switching:

• Preserves session tabs
• Switches active SDK client
• Updates SSE event routing

Session Tab Switching:

• Loads messages for that session
• Updates agent/model controls
• Preserves scroll position

Technology Stack

Core

• Electron - Desktop wrapper
• SolidJS - Reactive UI framework
• TypeScript - Type safety
• Vite - Build tool

UI

• TailwindCSS - Styling
• Kobalte - Accessible UI primitives
• Shiki - Code syntax highlighting
• Marked - Markdown parsing

Communication

• OpenCode SDK - API client
• EventSource - SSE streaming
• Node Child Process - Process spawning

Error Handling

Process Errors

• Server fails to start → Show error in instance tab
• Server crashes → Attempt auto-restart once
• Port already in use → Find next available port

Network Errors

• API call fails → Show inline error, allow retry
• SSE disconnects → Auto-reconnect with backoff
• Timeout → Show timeout error, allow manual retry

User Errors

• Invalid folder selection → Show error dialog
• Permission denied → Show actionable error message
• Out of memory → Graceful degradation message

Performance Considerations

Note: Performance optimization is NOT a focus for MVP. These are future considerations.

Message Rendering (Post-MVP)

• Start with simple list rendering - no virtual scrolling
• No message limits initially
• Only optimize if users report issues
• Virtual scrolling can be added in Phase 8 if needed

State Updates

• SolidJS fine-grained reactivity handles most cases
• No special optimizations needed for MVP
• Batching/debouncing can be added later if needed

Memory Management (Post-MVP)

• No memory management in MVP
• Let browser/OS handle it
• Add limits only if problems arise in testing

Security Considerations

• No remote code execution
• Server spawned with user permissions
• No eval() or dangerous innerHTML
• Sanitize markdown rendering
• Validate all IPC messages
• HTTPS only for external requests

Extensibility Points

Plugin System (Future)

• Custom slash commands
• Custom message renderers
• Theme extensions
• Keybinding customization

Configuration (Future)

• Per-instance settings
• Global preferences
• Workspace-specific configs
• Import/export settings