1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
# 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/`.
|
