diff options
Diffstat (limited to 'DESIGN.md')
| -rw-r--r-- | DESIGN.md | 177 |
1 files changed, 160 insertions, 17 deletions
@@ -20,6 +20,68 @@ The dashboard serves as a **personal consolidation hub** designed to: --- +## Development Workflow + +This project uses a **multi-agent development workflow** with three specialized roles that collaborate through shared documents. + +### Roles + +| Role | Agent | Responsibilities | +|------|-------|------------------| +| **Architect** | Gemini | Plans features, creates issues, writes surgical instructions. Does NOT edit source code. | +| **Implementor** | Claude Code | Executes plans, writes code, runs tests. Updates state after completing work. | +| **Reviewer** | QA Agent | Reviews code quality, runs tests, provides feedback. Does NOT edit source code. | + +### Role Definitions + +Each role has a detailed persona document: + +- `ARCHITECT_ROLE.md` - Planning, documentation, issue tracking +- `IMPLEMENTOR_ROLE.md` - Code execution, TDD, verification +- `REVIEWER_ROLE.md` - Quality gates, clean code review + +### Handoff Documents + +| Document | Purpose | Writer | Reader | +|----------|---------|--------|--------| +| `instructions.md` | Surgical implementation plan (ephemeral) | Architect | Implementor | +| `review_feedback.md` | Code review results (ephemeral) | Reviewer | Implementor | +| `SESSION_STATE.md` | Current state + next steps | All | All | +| `issues/*.md` | Bug reports + feature specs | Architect | All | +| `docs/adr/*.md` | Architectural decisions (permanent) | Architect | All | + +**Note:** `instructions.md` and `review_feedback.md` are ephemeral - they contain current task details. Architectural decisions belong in ADRs, not in ephemeral docs. + +### Status Tags + +Tasks flow through these states: + +``` +[TODO] → [IN_PROGRESS] → [REVIEW_READY] → [APPROVED] + ↑ ↓ + └── [NEEDS_FIX] ←┘ +``` + +### Workflow Example + +1. **Architect** identifies bug, creates `issues/bug_042_description.md` +2. **Architect** writes fix plan to `instructions.md`, updates `SESSION_STATE.md` to `[TODO]` +3. **Implementor** reads instructions, writes failing test (TDD), implements fix +4. **Implementor** runs `go test ./...`, updates state to `[REVIEW_READY]` +5. **Reviewer** reads code, runs tests, writes `review_feedback.md` +6. **Reviewer** marks `[APPROVED]` or `[NEEDS_FIX]` with specific feedback +7. If `[NEEDS_FIX]`, **Implementor** addresses feedback, returns to step 4 + +### Principles + +- **Surgical edits** - Prefer targeted changes over full-file rewrites +- **TDD** - Write failing test before implementation +- **State tracking** - Always update `SESSION_STATE.md` after completing work +- **Tool verification** - Use `go test`, `go build`, `grep` to verify state before planning +- **ADR-first** - Document architectural decisions in ADRs, not one-off design docs + +--- + ## Architecture ### Directory Structure @@ -330,6 +392,61 @@ Standalone live feeds page with: Auto-refresh webcam images every 60 seconds. +### Agent Context API (`/agent/*`) + +External agent authentication and data access system. Allows CLI tools, automation scripts, and AI assistants to access dashboard context securely. + +**Authentication Flow:** +1. Agent sends `POST /agent/auth/request` with name + agent_id (UUID) +2. Dashboard checks trust level: + - **TRUSTED**: Auto-approve if agent_id was previously approved + - **UNKNOWN**: Send WebSocket notification to connected browsers + - **BLOCKED**: Reject immediately +3. User approves/denies via modal in browser (pushed via WebSocket) +4. Agent polls `GET /agent/auth/poll?token=REQUEST_TOKEN` for result +5. On approval, agent receives session_token (1-hour TTL) +6. Agent uses session_token in Authorization header for context access + +**Endpoints:** + +| Method | Path | Auth | Purpose | +|--------|------|------|---------| +| POST | `/agent/auth/request` | None | Request access (returns request_token) | +| GET | `/agent/auth/poll` | None | Poll for approval status | +| POST | `/agent/auth/approve` | Browser session | User approves agent request | +| POST | `/agent/auth/deny` | Browser session | User denies agent request | +| GET | `/agent/context` | Agent session | Full timeline context (7 days back, 14 forward) | +| GET | `/agent/web/request` | None | HTML auth flow for browser-only agents | +| GET | `/agent/web/status` | None | HTML status page | +| GET | `/agent/web/context` | None | HTML context view | + +**WebSocket Notifications (`/ws/notifications`):** +- Pushes agent auth requests to connected browsers in real-time +- JSON protocol with auto-reconnect on disconnect +- Frontend handler in `web/static/js/app.js` + +**Security:** +- Rate limit: 10 requests/minute per IP on auth endpoints +- Session TTL: 1 hour, one active session per agent_id +- Impersonation detection: Rejects if name/agent_id mismatch previous binding + +**Implementation:** `internal/handlers/agent.go`, `internal/handlers/websocket.go` + +### Completed Tasks Log + +Tracks task completion history for audit trail and agent context. + +**Purpose:** +- Provides completion history in agent context API +- Enables future analytics/reporting +- Audit trail of completed work + +**Storage:** `completed_tasks` table (source, source_id, title, due_date, completed_at) + +**Feature Toggle:** `completed_log` (enabled by default) + +**Populated by:** `HandleCompleteAtom()` on task/card completion + --- ## Database Schema @@ -351,6 +468,11 @@ Auto-refresh webcam images every 60 seconds. | `shopping_item_checks` | External item state | source, item_id, checked | | `cache_metadata` | Cache timestamps | key, last_fetch, ttl_minutes | | `sync_tokens` | Incremental sync | service, token | +| `agents` | Registered agents | name, agent_id, trust_level, last_seen | +| `agent_sessions` | Agent auth sessions | agent_id, request_token, session_token, status, expires_at | +| `completed_tasks` | Completion log | source, source_id, title, due_date, completed_at | +| `feature_toggles` | Feature flags | name, description, enabled | +| `source_config` | Source filtering | source, item_type, item_id, item_name, enabled | --- @@ -705,22 +827,33 @@ func TestFeature_Behavior(t *testing.T) { - Add tests for new functionality - Update tests for changed behavior -### Design Documents and ADRs +### Architecture Decision Records (ADRs) -**When to update DESIGN.md:** -- Adding new features or views -- Changing data flow patterns -- Modifying API integrations -- Updating database schema +**ADRs are the primary way to document architectural decisions.** They capture the context, decision, and tradeoffs for significant choices. Unlike one-off design documents that become stale, ADRs remain as a permanent record of why things are the way they are. -**When to create an ADR (Architecture Decision Record):** +**Always create an ADR when:** - Choosing between multiple implementation approaches -- Adding new external dependencies -- Changing authentication/security model -- Significant refactoring decisions +- Adding new external dependencies or integrations +- Changing authentication, security, or data flow patterns +- Making significant refactoring decisions +- Introducing new patterns or abstractions + +**Do NOT create one-off design docs.** Instead: +- For feature planning → create an ADR with the architectural approach +- For implementation details → put them in `instructions.md` (ephemeral) +- For bug analysis → create an issue in `issues/` (ephemeral) **ADR location:** `docs/adr/NNN-title.md` +**Current ADRs:** +| ADR | Decision | +|-----|----------| +| 001 | Session-based authentication with SQLite storage | +| 002 | Polymorphic TimelineItem model for unified aggregation | +| 003 | HTMX partials for all write operations | +| 004 | Concurrent fetching with semaphore + cache fallback | +| 005 | Agent API notification-based authentication | + **ADR template:** ```markdown # ADR NNN: Title @@ -749,11 +882,11 @@ What did we decide and why? **Numbering:** Use sequential 3-digit numbers (001, 002, etc.) -**Example ADRs to consider:** -- API client retry strategy -- Caching invalidation approach -- New data source integration -- UI framework changes +**When to update DESIGN.md:** +- Adding new features or views (update Features section) +- New database tables (update Schema section) +- New API endpoints (update Quick Reference) +- Changes to the development workflow --- @@ -783,12 +916,22 @@ npx tailwindcss -i web/static/css/input.css -o web/static/css/output.css --watch | GET | `/tabs/timeline` | Timeline partial | | GET | `/tabs/tasks` | Tasks partial | | GET | `/tabs/shopping` | Shopping partial | -| GET | `/conditions` | Live feeds page | +| GET | `/conditions` | Live feeds page (public) | | POST | `/complete-atom` | Complete task/card | | POST | `/uncomplete-atom` | Reopen task/card | | POST | `/unified-add` | Quick add task | | POST | `/shopping/add` | Add shopping item | -| GET | `/shopping/mode/{store}` | Shopping mode | +| GET | `/shopping/mode/{store}` | Shopping mode view | +| POST | `/shopping/mode/{store}/toggle` | Toggle shopping item | +| POST | `/shopping/mode/{store}/complete` | Complete shopping item | +| GET | `/settings` | Settings page | +| POST | `/settings/features` | Create feature toggle | +| POST | `/settings/features/toggle` | Toggle feature on/off | +| GET | `/ws/notifications` | WebSocket for agent notifications | +| POST | `/agent/auth/request` | Agent requests access | +| GET | `/agent/auth/poll` | Agent polls for approval | +| POST | `/agent/auth/approve` | User approves agent | +| GET | `/agent/context` | Agent gets timeline context | ### Handler Signature |