# Coding Standards

This document defines the technical standards for the **Doot** project. Adherence to these standards ensures consistency, security, and maintainability.

## 1. Go (Backend)

### Idiomatic Go
- Follow standard Go idioms (Effective Go).
- Keep functions small and focused on a single responsibility.
- Use meaningful, descriptive names for variables, functions, and types.

### Concurrency
- Use `sync.WaitGroup` and `sync.Mutex` for managing concurrent operations.
- For parallel API fetching, use a semaphore pattern (e.g., buffered channel) to limit concurrency and avoid rate limits.
- **Example:** See `internal/api/trello.go` for the 5-request concurrency limit.

### Error Handling
- Use the "Partial Data / Cache Fallback" pattern: If an API call fails, return cached data (if available) or an empty set with an error logged, rather than failing the entire request.
- Use structured logging or the `data.Errors` slice in handlers to report non-fatal errors to the UI.

### Database (SQLite)
- **SQL Injection Prevention:** ALWAYS use parameterized queries (`?` placeholders).
- **Concurrency:** Enable WAL mode and set `MaxOpenConns(1)` to avoid "database is locked" errors.
- **Migrations:** All schema changes must be added as a new file in the `migrations/` directory.

### Project Structure
- `cmd/dashboard/`: Application entry point.
- `internal/api/`: External service clients (Todoist, Trello, etc.).
- `internal/auth/`: Authentication logic and middleware.
- `internal/config/`: Configuration loading and validation.
- `internal/handlers/`: HTTP request handlers and UI logic.
- `internal/models/`: Shared data structures.
- `internal/store/`: Database operations.

## 2. Frontend (HTMX + Tailwind CSS)

### HTMX
- Use HTMX for all state-changing operations (Create, Update, Delete) and tab switching.
- **Response Headers:** Use `HX-Trigger` and `HX-Reswap` to coordinate UI updates.
- **Partial Rendering:** Handlers should return HTML partials (from `web/templates/partials/`) for HTMX requests.

### CSS & Styling
- Use **Tailwind CSS** for all styling.
- Maintain a consistent mobile-first responsive design.
- Follow the Z-index hierarchy defined in `design.md`.

### User Feedback
- Provide immediate visual feedback for user actions (loading indicators, success/error banners).
- Ensure all forms clear their inputs upon successful submission.

## 3. Testing Philosophy

### Reproduction First
- Before fixing a bug, implement a failing test case that reproduces the issue.
- Verify the fix by ensuring the new test (and all existing tests) passes.

### Coverage Areas
- **Store:** Unit tests for all SQL operations (`sqlite_test.go`).
- **Handlers:** Integration tests for critical paths (`handlers_test.go`, `agent_test.go`).
- **API Clients:** Use mocks or test servers for external API testing (`todoist_test.go`, `trello_test.go`).

## 4. Documentation & Git

### Commit Messages
- Propose clear, concise messages that explain the "why" behind the change.
- Match existing style (usually imperative mood).

### File Header
- Maintain the standardized `SESSION_STATE.md` (now `worklog.md`) format.
- Document significant architectural changes in `docs/adr/`.