From b7728ff802caca04ef6cbe7d7253f630ce0fea20 Mon Sep 17 00:00:00 2001 From: yushen Date: Tue, 24 Mar 2026 14:25:33 +0800 Subject: [PATCH] docs: expand CLAUDE.md with architecture details and update lockfile Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 88 +++++++++++++++++++++++++++++++++++++++++--------- pnpm-lock.yaml | 9 ++++++ 2 files changed, 82 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 57c1342a..840b5f70 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,8 +1,8 @@ # CLAUDE.md -This file gives coding agents high-signal guidance for this repository. +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -## 1. Project Context +## Project Context Multica is an AI-native task management platform — like Linear, but with AI agents as first-class citizens. @@ -10,15 +10,56 @@ Multica is an AI-native task management platform — like Linear, but with AI ag - Supports local (daemon) and cloud agent runtimes - Built for 2-10 person AI-native teams -## 2. Architecture +## Architecture **Polyglot monorepo** — Go backend + TypeScript frontend. -- `server/` — Go backend (Chi + sqlc + gorilla/websocket) -- `apps/web/` — Next.js 16 frontend +- `server/` — Go backend (Chi router, sqlc for DB, gorilla/websocket for real-time) +- `apps/web/` — Next.js 16 frontend (App Router) - `packages/` — Shared TypeScript packages (ui, types, sdk, store, hooks, utils) -## 3. Core Workflow Commands +### Data Flow + +``` +Browser → ApiClient (SDK) → REST API (Chi handlers) → sqlc queries → PostgreSQL +Browser ← WSClient (SDK) ← WebSocket ← Hub.Broadcast() ← Handlers/TaskService +``` + +### Backend Structure (`server/`) + +- **Entry points** (`cmd/`): `server` (HTTP API), `daemon` (local agent runtime), `migrate`, `seed` +- **Handlers** (`internal/handler/`): One file per domain (issue, comment, agent, auth, daemon, etc.). Each handler holds `Queries`, `DB`, `Hub`, and `TaskService`. +- **Real-time** (`internal/realtime/`): Hub manages WebSocket clients. Server broadcasts events; inbound WS message routing is still TODO. +- **Auth** (`internal/auth/` + `internal/middleware/`): JWT (HS256). Middleware sets `X-User-ID` and `X-User-Email` headers. Login creates user on-the-fly if not found. +- **Task lifecycle** (`internal/service/task.go`): Orchestrates agent work — enqueue → claim → start → complete/fail. Syncs issue status automatically and broadcasts WS events at each transition. +- **Database**: sqlc generates Go code from SQL in `pkg/db/queries/` → `pkg/db/generated/`. Migrations in `migrations/`. +- **Routes** (`cmd/server/router.go`): Public routes (auth, health, ws) + protected routes (require JWT) + daemon routes (unauthenticated, separate auth model). + +### Frontend Structure (`apps/web/`) + +- **App Router layout groups**: `(auth)/` for login, `(dashboard)/` for protected routes +- **Auth context** (`lib/auth-context.tsx`): Global provider for user, workspace, members, agents. Hydrates from localStorage. Provides actor lookup helpers (`getMemberName`, `getAgentName`, `getActorName`). +- **WebSocket context** (`lib/ws-context.tsx`): Wraps `WSClient` from SDK. `useWSEvent()` hook auto-subscribes/unsubscribes. +- **API client** (`lib/api.ts`): Singleton `ApiClient` from `@multica/sdk`, initialized from localStorage. +- **State**: Zustand stores (`@multica/store`) for issues, agents, inbox. WebSocket events keep stores in sync without re-fetching. + +### Key Packages + +- **`@multica/sdk`**: `ApiClient` (REST) and `WSClient` (WebSocket) classes. All backend communication goes through here. +- **`@multica/types`**: Shared domain types + WebSocket event types (issue:created/updated/deleted, task:*, agent:status, comment:*, inbox:new, daemon:*). +- **`@multica/store`**: Zustand stores — simple arrays with add/update/remove. No persistence; memory only. +- **`@multica/ui`**: shadcn/ui component library with Radix primitives, Tailwind CSS 4, Shiki syntax highlighting for markdown. +- **`@multica/hooks`**: `useRealtime()` (WS → store sync), `useIssues()`, `useAgents()`, `useInbox()` (fetch + cache). + +### Multi-tenancy + +All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace. + +### Agent Assignees + +Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon). + +## Commands ```bash # One-click setup & run @@ -38,17 +79,34 @@ pnpm test # TS tests (Vitest) make dev # Run Go server (port 8080) make daemon # Run local daemon make test # Go tests -make sqlc # Regenerate sqlc code +make sqlc # Regenerate sqlc code after editing SQL in server/pkg/db/queries/ make migrate-up # Run database migrations make migrate-down # Rollback migrations -make seed # Seed example data + +# Run a single Go test +cd server && go test ./internal/handler/ -run TestName + +# Run a single TS test +pnpm --filter @multica/web exec vitest run src/path/to/file.test.ts + +# Run a single E2E test (requires backend + frontend running) +pnpm exec playwright test e2e/tests/specific-test.spec.ts # Infrastructure docker compose up -d # Start PostgreSQL docker compose down # Stop PostgreSQL ``` -## 4. Coding Rules +### Worktree Support + +For isolated feature testing with a separate database: +```bash +make worktree-env # Generate .env.worktree with unique DB/ports +make setup-worktree # Setup using .env.worktree +make start-worktree # Start using .env.worktree +``` + +## Coding Rules - TypeScript strict mode is enabled; keep types explicit. - Go code follows standard Go conventions (gofmt, go vet). @@ -59,19 +117,19 @@ docker compose down # Stop PostgreSQL - Treat compatibility code as a maintenance cost, not a default safety mechanism. Avoid "just in case" branches that make the codebase harder to reason about. - Avoid broad refactors unless required by the task. -## 5. UI/UX Rules +## UI/UX Rules - Prefer `packages/ui` shadcn components over custom implementations. - Do not introduce extra state (useState, context, reducers) unless explicitly required by the design. - Pay close attention to **overflow** (truncate long text, scrollable containers), **alignment**, and **spacing** consistency. - When unsure about interaction or state design, ask — the user will provide direction. -## 6. Testing Rules +## Testing Rules - **TypeScript**: Vitest. Mock external/third-party dependencies only. - **Go**: Standard `go test`. Use testcontainers or test database for DB tests. -## 7. Commit Rules +## Commit Rules - Use atomic commits grouped by logical intent. - Conventional format: @@ -82,7 +140,7 @@ docker compose down # Stop PostgreSQL - `test(scope): ...` - `chore(scope): ...` -## 8. Minimum Pre-Push Checks +## Minimum Pre-Push Checks ```bash make check # Runs all checks: typecheck, unit tests, Go tests, E2E @@ -96,7 +154,7 @@ make test # Go tests only pnpm exec playwright test # E2E only (requires backend + frontend running) ``` -## 9. AI Agent Verification Loop +## AI Agent Verification Loop After writing or modifying code, always run the full verification pipeline: @@ -119,7 +177,7 @@ This runs all checks in sequence: **Quick iteration:** If you know only TypeScript or Go is affected, run individual checks first for faster feedback, then finish with a full `make check` before marking work complete. -## 10. E2E Test Patterns +## E2E Test Patterns E2E tests should be self-contained. Use the `TestApiClient` fixture for data setup/teardown: diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 633a5bc9..d2c1d540 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -140,6 +140,15 @@ importers: specifier: ^4.1.0 version: 4.1.0(@types/node@25.5.0)(jsdom@29.0.1(@noble/hashes@1.8.0))(msw@2.12.14(@types/node@25.5.0)(typescript@5.9.3))(vite@8.0.1(@types/node@25.5.0)(jiti@2.6.1)) + packages/agent-sdk: + devDependencies: + '@types/node': + specifier: 'catalog:' + version: 25.5.0 + typescript: + specifier: 'catalog:' + version: 5.9.3 + packages/hooks: dependencies: '@multica/sdk':