OpenParable
Skip to content
← Back to skills

Codenomad Architecture Guide

Development
codenomad-architecture-guide

Codenomad Architecture Guide is an Agent Skill for development published in the NeuralNomadsAI/CodeNomad repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Comprehensive architecture and SDK navigation guide for the CodeNomad codebase. **When to use:** Load this skill when you need to navigate the CodeNomad monorepo, understand cross-package dependencies, work with the OpenCode SDK V2, or ensure you don't miss related code when implementing features or fixing bugs. This skill covers the 6 functional areas (ServerBackend, UserInterface, DesktopClient, SpeechAndAudio, BuildAndPackaging, CloudflareDeployment), OpenCode SDK V2 integration patterns, critical schema behaviors, and feature traces with decision branches. **Trigger contexts:** Working on CodeNomad features, debugging cross-area issues, integrating OpenCode SDK APIs, adding UI components, implementing server routes, or navigating the monorepo structure. **Permission required:** Agent must explicitly request or be granted permission to load this skill.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/NeuralNomadsAI/CodeNomad/blob/HEAD/.opencode/skills/codenomad-architecture-guide/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/codenomad-architecture-guide, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

CodeNomad Architecture & SDK Navigation Skill

Quick Start (by contribution frequency)

  • UI component/feature (60%) → Read references/ui-conventions.md → Check i18n
  • Server route/feature (25%) → Read references/server-conventions.md → Check references/feature-traces.md
  • Bug fix (10%) → Use Navigation Guide below → Check references/feature-traces.md
  • Desktop/Plugin (5%) → Read references/desktop-conventions.md
  • Not covered? → See "Escape Hatch" at bottom

1. Architecture Overview

CodeNomad is a multi-platform desktop application with a Fastify backend and SolidJS frontend.

6 Functional Areas (from RPG analysis)

AreaEntitiesKey Responsibility
UserInterface613SolidJS components, stores, hooks, i18n, API client
ServerBackend418Fastify routes, auth, workspaces, filesystem, speech
SpeechAndAudio74Speech synthesis, voice mode, conversation mode
DesktopClient59Electron main, Tauri Rust, preload, IPC
BuildAndPackaging28Build scripts, packaging, resource bundling
CloudflareDeployment3Edge deployment, asset serving

Package Map

  • packages/server/ — Fastify backend, workspaces, auth, speech, sidecars
  • packages/ui/ — SolidJS frontend, stores, components, i18n
  • packages/electron-app/ — Electron desktop wrapper
  • packages/tauri-app/ — Tauri desktop wrapper (Rust + webview)
  • packages/opencode-plugin/ — OpenCode plugin integration

Key Entry Points

  • Server: packages/server/src/index.ts (CLI entry)
  • UI: packages/ui/src/main.tsx (app bootstrap)
  • Electron: packages/electron-app/electron/main/main.ts
  • Tauri: packages/tauri-app/src-tauri/src/main.rs

2. Navigation Guide

Finding Code in the Codebase

Use grep and file search tools to navigate:

Search by intent:

  • grep "permission approval" packages/ui/src/components/
  • grep "session list" packages/ui/src/stores/
  • grep "workspace create" packages/server/src/server/routes/

Search by imports:

  • Find what uses a module: grep "import.*from.*module-path" packages/
  • Find exports: grep "^export" packages/server/src/api-types.ts

Cross-reference by feature:

  • Server API types: packages/server/src/api-types.ts
  • UI type mirrors: packages/ui/src/types/
  • SDK wrappers: packages/ui/src/lib/sdk-manager.ts

3. SDK Schema Verification (Mandatory)

SDK Note: The OpenCode SDK is an external package (@opencode-ai/sdk/v2/client). Its implementation lives outside this repository.

  • After npm install, you can inspect types in node_modules/@opencode-ai/sdk/v2/client.d.ts
  • Fallback: Read the actual usage patterns in CodeNomad code (see references/sdk-api-reference.md for file locations)
  • When in doubt, check how the SDK is imported and used in existing CodeNomad files

This skill provides navigation and patterns, not definitive schemas.

4. Anti-Patterns

Common Mistakes

MistakeCorrect ApproachReference
Import enMessages directlyUse t() or tGlobal()packages/ui/src/lib/i18n/index.tsx
Set metadata: { flag: true } on assistant partsUse client-side registrypackages/ui/src/stores/session-compaction.ts
Call client.session.* directly without worktree routingUse getOrCreateWorktreeClient()packages/ui/src/stores/worktrees.ts
Forget SSE disconnection handlingAdd handlerspackages/ui/src/lib/event-source-handlers.ts
Add hardcoded strings without i18nAdd to English + all 7 localespackages/ui/src/lib/i18n/messages/
Modify server route without checking UI API clientTrace full feature flowreferences/feature-traces.md
Change API type without checking UI type matchesCheck UI types mirror server typespackages/ui/src/types/ vs packages/server/src/api-types.ts

5. Platform Integration Checklist

Desktop Platform Rules

  • Existing IPC/handlers (pre-Tauri): MUST implement in both Electron + Tauri
  • New features: Implement in Electron first, Tauri if time permits
  • Native APIs (dialogs, notifications): Use packages/ui/src/lib/native/ abstraction

Checklist

  • Electron main-process changes? (packages/electron-app/electron/main/)
  • Tauri Rust changes? (packages/tauri-app/src-tauri/src/)
  • Preload API exposure? (packages/electron-app/electron/preload/)
  • Native abstraction? (packages/ui/src/lib/native/)

6. Implementation Checklist

Before submitting changes:

  • Run impact analysis: grep "YOUR_EXPORT_NAME" packages/ to find all usages
  • Check i18n: Search for hardcoded strings in modified files
  • Verify file length: Check line count (warn >500, reject >800 source; >1000 tests)
  • Check DesktopClient: Does this need IPC/main-process changes?
  • Verify SDK compatibility: Check types in node_modules/@opencode-ai/sdk/v2/client.d.ts
  • Cross-area check: If modifying server routes, check UI stores and API clients
  • Check anti-patterns: Review "Common Mistakes" section above
  • API compatibility: If changing api-types.ts, check UI type matches

7. Escape Hatch + Update Criteria

Not Covered?

If your change involves areas not documented here:

  1. Read package entry points and scan directory structure
  2. Ask the user before proceeding with unfamiliar code

Update This Skill If

  • You discover a new SDK gotcha not documented in references/sdk-critical-behaviors.md
  • You add a new cross-area feature flow (add to references/feature-traces.md)
  • File paths or conventions change significantly
  • You find an anti-pattern occurring repeatedly
  • SDK schemas change and examples become outdated

Reference Files

FilePurpose
references/architecture-overview.mdPackage structure, functional areas, entry points
references/ui-conventions.mdSolidJS, i18n, stores, components, testing
references/server-conventions.mdFastify, API types, config, testing
references/desktop-conventions.mdElectron + Tauri parity, native abstractions
references/sdk-api-reference.mdOpenCode SDK V2 categories and signatures
references/sdk-critical-behaviors.mdSchema gotchas, limitations, decision matrix
references/sdk-integration-patterns.mdClient lifecycle, error handling, optimistic updates
references/feature-traces.mdEnd-to-end flows with decision branches