# Codewalk District

Multi-agent workspace for orchestrating multiple AI coding agents working in parallel on a shared codebase.

**Architecture**: [docs/architecture.md](docs/architecture.md) — system diagram, module map, entity relationships, tech stack.

## Quick Reference

| Module | Docs | Path |
|--------|------|------|
| Agent (lifecycle, providers, accounts) | [docs/agent.md](docs/agent.md) | `src/agent/` |
| Database (schema, repositories) | [docs/database.md](docs/database.md) | `src/db/` |
| Server & API (tRPC procedures) | [docs/server-api.md](docs/server-api.md) | `src/server/`, `src/trpc/`, `src/coordination/` |
| Frontend (React UI) | [docs/frontend.md](docs/frontend.md) | `packages/web/` |
| CLI & Config | [docs/cli-config.md](docs/cli-config.md) | `src/cli/`, `src/config/` |
| Dispatch & Events | [docs/dispatch-events.md](docs/dispatch-events.md) | `src/dispatch/`, `src/events/` |
| Git, Process, Logging | [docs/git-process-logging.md](docs/git-process-logging.md) | `src/git/`, `src/process/`, `src/logger/`, `src/logging/` |
| Preview (Docker deployments) | [docs/preview.md](docs/preview.md) | `src/preview/` |
| Testing | [docs/testing.md](docs/testing.md) | `src/test/` |
| Database Migrations | [docs/database-migrations.md](docs/database-migrations.md) | `drizzle/` |
| Logging Guide | [docs/logging.md](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 generate` and the migration system. See [docs/database-migrations.md](docs/database-migrations.md).
- **Logging**: Use `createModuleLogger()` from `src/logger/index.ts`. Keep `console.log` for CLI user-facing output only.
- **Hexagonal architecture**: Repository ports in `src/db/repositories/*.ts`, Drizzle adapters in `src/db/repositories/drizzle/*.ts`. All re-exported from `src/db/index.ts`.
- **tRPC context**: Optional repos accessed via `require*Repository()` helpers in `src/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

```sh
npm run build && npm link
```

Run after any change to server-side code (`src/**`).

## Testing

```sh
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](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.