270a5cb21d
Preview deployments let reviewers spin up the app at a specific branch in local Docker containers, accessible through a single Caddy reverse proxy port. Docker is the source of truth — no database table needed. New module: src/preview/ with config discovery (.cw-preview.yml → compose → Dockerfile fallback), compose generation, Docker CLI wrapper, health checking, and port allocation (9100-9200 range).
2.7 KiB
2.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 | src/agent/ |
| Database (schema, repositories) | docs/database.md | src/db/ |
| Server & API (tRPC procedures) | docs/server-api.md | src/server/, src/trpc/, src/coordination/ |
| Frontend (React UI) | docs/frontend.md | packages/web/ |
| CLI & Config | docs/cli-config.md | src/cli/, src/config/ |
| Dispatch & Events | docs/dispatch-events.md | src/dispatch/, src/events/ |
| Git, Process, Logging | docs/git-process-logging.md | src/git/, src/process/, src/logger/, src/logging/ |
| Preview (Docker deployments) | docs/preview.md | src/preview/ |
| Testing | docs/testing.md | src/test/ |
| Database Migrations | docs/database-migrations.md | drizzle/ |
| Logging Guide | docs/logging.md | src/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()fromsrc/logger/index.ts. Keepconsole.logfor CLI user-facing output only. - Hexagonal architecture: Repository ports in
src/db/repositories/*.ts, Drizzle adapters insrc/db/repositories/drizzle/*.ts. All re-exported fromsrc/db/index.ts. - tRPC context: Optional repos accessed via
require*Repository()helpers insrc/trpc/routers/_helpers.ts.
Build
npm run build && npm link
Run after any change to server-side code (src/**).
Testing
npm test # Unit tests
REAL_CLAUDE_TESTS=1 npm test -- src/test/integration/real-providers/ --test-timeout=300000 # Real provider tests (~$0.50)
See docs/testing.md for details.
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.