34578d39c6
Move src/ → apps/server/ and packages/web/ → apps/web/ to adopt standard monorepo conventions (apps/ for runnable apps, packages/ for reusable libraries). Update all config files, shared package imports, test fixtures, and documentation to reflect new paths. Key fixes: - Update workspace config to ["apps/*", "packages/*"] - Update tsconfig.json rootDir/include for apps/server/ - Add apps/web/** to vitest exclude list - Update drizzle.config.ts schema path - Fix ensure-schema.ts migration path detection (3 levels up in dev, 2 levels up in dist) - Fix tests/integration/cli-server.test.ts import paths - Update packages/shared imports to apps/server/ paths - Update all docs/ files with new paths
3.7 KiB
Codewalk District
Multi-agent workspace for orchestrating multiple AI coding agents working in parallel on a shared codebase.
Architecture: docs/architecture.md — system diagram, module map, entity relationships, tech stack.
Quick Reference
| Module | Docs | Path |
|---|---|---|
| Agent (lifecycle, providers, accounts) | docs/agent.md | apps/server/agent/ |
| Database (schema, repositories) | docs/database.md | apps/server/db/ |
| Server & API (tRPC procedures) | docs/server-api.md | apps/server/server/, apps/server/trpc/, apps/server/coordination/ |
| Frontend (React UI) | docs/frontend.md | apps/web/ |
| CLI & Config | docs/cli-config.md | apps/server/cli/, apps/server/config/ |
| Dispatch & Events | docs/dispatch-events.md | apps/server/dispatch/, apps/server/events/ |
| Git, Process, Logging | docs/git-process-logging.md | apps/server/git/, apps/server/process/, apps/server/logger/, apps/server/logging/ |
| Preview (Docker deployments) | docs/preview.md | apps/server/preview/ |
| Testing | docs/testing.md | apps/server/test/ |
| Database Migrations | docs/database-migrations.md | drizzle/ |
| Logging Guide | docs/logging.md | apps/server/logger/ |
Pre-implementation design docs are archived in docs/archive/.
Key Rules
- Database: Never use raw SQL for schema initialization. Use
drizzle-kit generateand the migration system. See docs/database-migrations.md. - Logging: Use
createModuleLogger()fromapps/server/logger/index.ts. Keepconsole.logfor CLI user-facing output only. - Hexagonal architecture: Repository ports in
apps/server/db/repositories/*.ts, Drizzle adapters inapps/server/db/repositories/drizzle/*.ts. All re-exported fromapps/server/db/index.ts. - tRPC context: Optional repos accessed via
require*Repository()helpers inapps/server/trpc/routers/_helpers.ts.
UI Patterns
- Shift+click to skip confirmation: Destructive actions (delete task, etc.) show a
window.confirm()dialog on click. Holding Shift bypasses the dialog and executes immediately. Apply this pattern to all new destructive buttons.
Build
npm run build && npm link
Run after any change to server-side code (apps/server/**).
Testing
npm test # Unit + E2E tests (no API cost)
CW_CASSETTE_RECORD=1 npm test -- <test-file> # Record new cassettes locally
REAL_CLAUDE_TESTS=1 npm test -- apps/server/test/integration/real-providers/ --test-timeout=300000 # Real provider tests (~$0.50)
# Record full-flow cassettes (one-time, costs ~$2–5 in API credits):
CW_CASSETTE_RECORD=1 npm test -- apps/server/test/integration/full-flow/full-flow-cassette.test.ts --test-timeout=3600000
# Commit the generated apps/server/test/cassettes/<hash>.json files afterward.
# Subsequent runs replay from cassettes at no cost: npm test
See docs/testing.md for details, including the cassette system for pipeline integration tests that run without API costs.
Documentation Maintenance
After every code change, update the relevant docs/ file. Documentation must stay in sync with implementation. When adding a new module, table, tRPC procedure, component, or CLI command, update the corresponding doc. When refactoring, update affected docs and remove stale information.
Committing
After completing & verifying changes always commit the changes.