adiuva/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Development
source ~/.nvm/nvm.sh && npm start          # Start Electron app with hot-reload

# Build & Package
source ~/.nvm/nvm.sh && npm run make       # Build distributable packages
source ~/.nvm/nvm.sh && npm run package    # Package without making installers

# Lint
source ~/.nvm/nvm.sh && npm run lint       # ESLint over .ts/.tsx files

# Database migrations (Drizzle)
source ~/.nvm/nvm.sh && npx drizzle-kit generate   # Generate migration from schema changes
source ~/.nvm/nvm.sh && npx drizzle-kit push        # Push schema directly (dev only)

There is no test suite currently.

Architecture Overview

Adiuva is a local-first Electron desktop app. The three Electron processes communicate via a custom tRPC↔IPC bridge (the public electron-trpc package is incompatible with tRPC v11, so a custom implementation is used).

Process Boundaries

Renderer (React)  ──ipcLink──►  Preload (contextBridge)  ──IPC──►  Main (tRPC router + SQLite)

1. Main process (src/main/) — Node.js, owns the database and all business logic

   • index.ts — Window creation, app lifecycle
   • ipc.ts — Custom handler that bridges ipcMain to tRPC procedures
   • router/index.ts — All tRPC routers (clients, projects, tasks, checkpoints, notes, settings, ai)
   • db/index.ts — Drizzle + better-sqlite3, WAL mode, singleton getDb()
   • db/schema.ts — All table definitions (clients, projects, tasks, checkpoints, notes)
   • store.ts — electron-store for persistent UI settings (e.g., sidebarCollapsed)

2. Preload (src/preload/trpc.ts) — Exposes window.electronTRPC with sendMessage() / onMessage()

3. Renderer (src/renderer/) — React 19, never accesses Node APIs directly

   • lib/ipcLink.ts — Custom TRPCLink that routes calls through window.electronTRPC
   • lib/trpc.ts — createTRPCReact<AppRouter>() typed client
   • index.tsx — QueryClient + tRPC + Router providers
   • All data access is through trpc.*.*useQuery() / trpc.*.*.useMutation()

Routing

File-based routing via TanStack Router. Add a file to src/renderer/routes/ and the route tree (src/renderer/routeTree.gen.ts) is auto-regenerated by the Vite plugin on next npm start. Routes:

• __root.tsx — Root layout wrapping everything in AppShell
• index.tsx, tasks.tsx, timeline.tsx, projects.tsx

Database

Schema lives in src/main/db/schema.ts. Migrations are in src/main/db/migrations/. The DB is created in Electron's userData directory as adiuva.db. On startup, initDb() runs non-destructive migrations (CREATE TABLE IF NOT EXISTS).

To add a new table or column: edit schema.ts, run drizzle-kit generate, then drizzle-kit push (dev) or commit the migration file.

Adding a New Feature (end-to-end pattern)

1. Schema — Add table/columns to src/main/db/schema.ts
2. Router — Add a tRPC sub-router in src/main/router/index.ts, merge it into appRouter
3. Types — AppRouter is exported from src/main/router/index.ts and imported in src/renderer/lib/trpc.ts — types flow automatically
4. UI — Create components under src/renderer/components/<feature>/, use trpc.*.*useQuery() for data

Key Config Notes

• Vite configs use .mts extension (not .ts) to avoid ESM/CJS conflicts with electron-forge's externalize-deps plugin
• @/* path alias resolves to src/renderer/* (TypeScript + Vite + shadcn/ui all share this alias)
• shadcn/ui style: new-york, base color: neutral
• Icons: lucide-react throughout — do not introduce other icon libraries
• Tailwind 4 (not 3) — use CSS variable theming via globals.css, not tailwind.config.js