codenomad-architecture-guide

name

codenomad-architecture-guide

description

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.

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)

Area	Entities	Key Responsibility
UserInterface	613	SolidJS components, stores, hooks, i18n, API client
ServerBackend	418	Fastify routes, auth, workspaces, filesystem, speech
SpeechAndAudio	74	Speech synthesis, voice mode, conversation mode
DesktopClient	59	Electron main, Tauri Rust, preload, IPC
BuildAndPackaging	28	Build scripts, packaging, resource bundling
CloudflareDeployment	3	Edge 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

Mistake	Correct Approach	Reference
Import enMessages directly	Use t() or tGlobal()	packages/ui/src/lib/i18n/index.tsx
Set metadata: { flag: true } on assistant parts	Use client-side registry	packages/ui/src/stores/session-compaction.ts
Call client.session.* directly without worktree routing	Use getOrCreateWorktreeClient()	packages/ui/src/stores/worktrees.ts
Forget SSE disconnection handling	Add handlers	packages/ui/src/lib/event-source-handlers.ts
Add hardcoded strings without i18n	Add to English + all 7 locales	packages/ui/src/lib/i18n/messages/
Modify server route without checking UI API client	Trace full feature flow	references/feature-traces.md
Change API type without checking UI type matches	Check UI types mirror server types	packages/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

File	Purpose
references/architecture-overview.md	Package structure, functional areas, entry points
references/ui-conventions.md	SolidJS, i18n, stores, components, testing
references/server-conventions.md	Fastify, API types, config, testing
references/desktop-conventions.md	Electron + Tauri parity, native abstractions
references/sdk-api-reference.md	OpenCode SDK V2 categories and signatures
references/sdk-critical-behaviors.md	Schema gotchas, limitations, decision matrix
references/sdk-integration-patterns.md	Client lifecycle, error handling, optimistic updates
references/feature-traces.md	End-to-end flows with decision branches