path: root/implementation-plan.md

# Implementation Plan: Personal Consolidation Dashboard

## Project Overview
Build a unified web dashboard aggregating tasks (Todoist), notes (Obsidian), and meal planning (PlanToEat) using Go backend and responsive frontend.

## Development Phases

### Phase 1: Foundation & Read-Only Aggregation (MVP)
**Goal:** Display aggregated data from all services in a single dashboard

#### Step 1: Project Setup
- [x] Initialize Go module (`go mod init`)
- [ ] Create project directory structure
- [ ] Set up `.env.example` with all required API keys
- [ ] Add `.gitignore` for Go projects
- [ ] Create `README.md` with setup instructions

#### Step 2: Core Backend Infrastructure
**Priority: High**

1. **Database Layer** (`internal/store/sqlite.go`)
   - Initialize SQLite connection
   - Create tables for cached data:
     - `tasks` (Todoist)
     - `notes` (Obsidian)
     - `meals` (PlanToEat)
     - `cache_metadata` (last fetch times, TTL)
   - Implement CRUD operations
   - Add migration support (manual SQL files in `migrations/`)

2. **Configuration** (`internal/config/config.go`)
   - Load environment variables
   - Validate required API keys
   - Provide configuration struct to handlers

3. **Data Models** (`internal/models/types.go`)
   - Implement Task struct (Todoist)
   - Implement Note struct (Obsidian)
   - Implement Meal struct (PlanToEat)
   - Implement Board/Card structs (Trello - optional)

#### Step 3: API Integrations (Sequential Implementation)
**Priority: High**

**3.1: Todoist Integration** (`internal/api/todoist.go`)
- Implement HTTP client with Bearer token auth
- Create `GetTasks()` - fetch all active tasks
- Create `GetProjects()` - fetch project list
- Parse API responses into Task structs
- Add error handling and rate limiting
- Test with real API token

**3.2: Obsidian Integration** (`internal/api/obsidian.go`)
- Read vault directory from env variable
- Implement file scanner (limit to 20 most recent)
- Parse markdown files
- Extract YAML frontmatter for tags/metadata
- Handle file read errors gracefully

**3.3: PlanToEat Integration** (`internal/api/plantoeat.go`)
- Implement HTTP client with API key auth
- Create `GetPlannerItems()` - fetch upcoming meals (7 days)
- Create `GetRecipeDetails()` - fetch recipe info
- Parse API responses into Meal structs
- Add error handling

**3.4: Trello Integration (Optional)** (`internal/api/trello.go`)
- Implement HTTP client with API Key + Token
- Create `GetBoards()` - fetch user's boards
- Create `GetCards()` - fetch cards from specific boards
- Parse API responses

#### Step 4: Backend HTTP Handlers
**Priority: High**

1. **Main Server** (`cmd/dashboard/main.go`)
   - Set up HTTP server with chi/gorilla router
   - Configure static file serving (`/static/*`)
   - Configure template rendering
   - Add graceful shutdown
   - Start server on port from env (default 8080)

2. **Dashboard Handler** (`internal/handlers/dashboard.go`)
   - Implement `GET /` - main dashboard view
   - Aggregate data from all sources in parallel (goroutines)
   - Check cache freshness (5min TTL)
   - Refresh stale data from APIs
   - Render dashboard template with aggregated data

3. **API Endpoints** (`internal/handlers/api.go`)
   - `GET /api/tasks` - return tasks as JSON
   - `GET /api/notes` - return notes as JSON
   - `GET /api/meals` - return meals as JSON
   - `POST /api/refresh` - force refresh all data
   - Add CORS headers if needed

#### Step 5: Frontend Development
**Priority: High**

1. **Base Template** (`web/templates/base.html`)
   - HTML5 boilerplate
   - Include Tailwind CSS (CDN or built)
   - Include HTMX (if chosen) or vanilla JS
   - Mobile viewport meta tag
   - Basic responsive grid layout

2. **Dashboard View** (`web/templates/index.html`)
   - Header with refresh button
   - Quick capture section (placeholder for Phase 2)
   - Tasks section (today + week view)
   - Meals section (upcoming 7 days)
   - Notes section (recent 10 notes)
   - Loading spinners
   - Error message display

3. **Styling** (`web/static/css/styles.css`)
   - Mobile-first responsive design
   - Card-based layout for each section
   - Dark mode support (optional)
   - Loading states
   - Hover effects and transitions

4. **Interactivity** (`web/static/js/app.js`)
   - Auto-refresh every 5 minutes
   - Manual refresh button handler
   - Show/hide loading states
   - Error handling UI
   - Task filtering (all/today/week)

#### Step 6: Testing & Refinement
**Priority: Medium**

- Test with real API keys for all services
- Test on mobile browser (Chrome/Safari)
- Verify responsive design breakpoints
- Test error scenarios (API down, invalid keys)
- Verify cache TTL behavior
- Test concurrent API calls

### Phase 2: Write Operations
**Goal:** Enable creating and updating data across services

#### Step 1: Todoist Write Operations
**Priority: High**

1. **API Methods** (`internal/api/todoist.go`)
   - `CreateTask(content, projectID, dueDate, priority)` - POST /tasks
   - `CompleteTask(taskID)` - POST /tasks/{id}/close
   - `UpdateTask(taskID, updates)` - POST /tasks/{id}

2. **HTTP Handlers** (`internal/handlers/tasks.go`)
   - `POST /api/tasks` - create new task
   - `POST /api/tasks/:id/complete` - mark task complete
   - `PUT /api/tasks/:id` - update task
   - Return JSON responses
   - Invalidate cache after mutations

3. **Frontend Updates**
   - Add task creation form in quick capture section
   - Add checkbox click handler for task completion
   - Add inline edit for task content
   - Show success/error notifications
   - Update UI optimistically with rollback on error

#### Step 2: Obsidian Write Operations
**Priority: Medium**

1. **API Methods** (`internal/api/obsidian.go`)
   - `CreateNote(title, content, tags)` - write to vault directory
   - Generate filename from title (slugify)
   - Add YAML frontmatter with metadata
   - Handle file write errors

2. **HTTP Handlers** (`internal/handlers/notes.go`)
   - `POST /api/notes` - create new note
   - Accept markdown content
   - Return created note details

3. **Frontend Updates**
   - Add note creation form
   - Markdown preview (optional)
   - Tag input field
   - Success notification with link to note

#### Step 3: PlanToEat Write Operations (Optional)
**Priority: Low**

1. **API Methods** (`internal/api/plantoeat.go`)
   - `AddMealToPlanner(recipeID, date, mealType)` - POST to planner
   - `GetRecipes()` - search recipes for selection

2. **HTTP Handlers** (`internal/handlers/meals.go`)
   - `POST /api/meals` - add meal to planner
   - `GET /api/recipes/search` - search recipes

3. **Frontend Updates**
   - Add meal planning interface
   - Recipe search/selection
   - Date and meal type picker

### Phase 3: Enhancements
**Goal:** Advanced features and polish

#### Planned Features
1. **Unified Search**
   - Search across tasks, notes, and meals
   - Full-text search using SQLite FTS5
   - Search results page with highlighting

2. **Quick Capture**
   - Single input that intelligently routes to correct service
   - Parse natural language (e.g., "task: buy milk" vs "note: meeting notes")
   - Keyboard shortcut support

3. **Daily Digest**
   - `/digest` route showing day-at-a-glance
   - Upcoming tasks, today's meals, pinned notes
   - Export as markdown or email

4. **PWA Configuration**
   - Add `manifest.json` for installability
   - Service worker for offline caching
   - App icon and splash screen

5. **Data Visualization**
   - Task completion trends
   - Meal planning calendar view
   - Note creation frequency

## Technical Decisions

### Resolved
- **Routing:** Use `chi` router (lightweight, stdlib-like)
- **Database:** SQLite with manual migrations
- **Frontend:** HTMX + Tailwind CSS (CDN) for rapid development
- **Obsidian Scanning:** Flat directory scan with mtime sorting (avoid deep recursion)

### To Decide During Implementation
- [ ] Full Tailwind build vs CDN (start with CDN, optimize later)
- [ ] Trello integration in Phase 1 or defer to Phase 3
- [ ] Dark mode toggle persistence (localStorage vs cookie)
- [ ] Cache invalidation strategy (TTL vs event-based)

## File Structure
```
task-dashboard/
├── cmd/
│   └── dashboard/
│       └── main.go
├── internal/
│   ├── api/
│   │   ├── todoist.go
│   │   ├── plantoeat.go
│   │   ├── trello.go
│   │   └── obsidian.go
│   ├── config/
│   │   └── config.go
│   ├── handlers/
│   │   ├── dashboard.go
│   │   ├── tasks.go
│   │   ├── notes.go
│   │   └── meals.go
│   ├── models/
│   │   └── types.go
│   └── store/
│       └── sqlite.go
├── web/
│   ├── static/
│   │   ├── css/
│   │   │   └── styles.css
│   │   └── js/
│   │       └── app.js
│   └── templates/
│       ├── base.html
│       ├── index.html
│       ├── tasks.html
│       └── notes.html
├── migrations/
│   ├── 001_initial_schema.sql
│   └── 002_add_cache_metadata.sql
├── .env.example
├── .gitignore
├── go.mod
├── go.sum
├── README.md
├── spec.md
└── implementation-plan.md
```

## Environment Variables (.env.example)
```bash
# API Keys
TODOIST_API_KEY=your_todoist_token
PLANTOEAT_API_KEY=your_plantoeat_key
TRELLO_API_KEY=your_trello_api_key
TRELLO_TOKEN=your_trello_token

# Paths
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
DATABASE_PATH=./dashboard.db

# Server
PORT=8080
CACHE_TTL_MINUTES=5
```

## Development Workflow

### Day 1-2: Foundation
1. Set up project structure
2. Implement SQLite database layer
3. Create configuration loader
4. Define all data models

### Day 3-4: API Integrations
1. Implement Todoist client (highest priority)
2. Implement Obsidian file reader
3. Implement PlanToEat client
4. Test all API clients independently

### Day 5-6: Backend Server
1. Set up HTTP server with routing
2. Implement dashboard handler with caching
3. Create API endpoints
4. Test with Postman/curl

### Day 7-8: Frontend
1. Build HTML templates
2. Add Tailwind styling
3. Implement JavaScript interactivity
4. Test responsive design

### Day 9-10: Phase 1 Polish
1. Error handling improvements
2. Loading states and UX polish
3. Mobile testing
4. Documentation

### Week 2+: Phase 2 & 3
- Implement write operations
- Add enhancements based on usage
- Deploy to Docker/Fly.io

## Testing Strategy

### Unit Tests
- API client functions
- Data model parsing
- Cache logic

### Integration Tests
- Full API roundtrips (with mocked responses)
- Database operations
- Handler responses

### Manual Testing
- Real API integration with personal accounts
- Mobile browser testing (Chrome DevTools + real device)
- Error scenarios (network failures, invalid keys)

## Success Metrics

### Phase 1 Complete When:
- [ ] Dashboard shows Todoist tasks (today + week)
- [ ] Dashboard shows 10 most recent Obsidian notes
- [ ] Dashboard shows 7 days of PlanToEat meals
- [ ] Responsive on mobile (320px-1920px)
- [ ] Auto-refresh works (5min)
- [ ] Manual refresh button works
- [ ] Runs with `go run cmd/dashboard/main.go`
- [ ] Can deploy with Docker

### Phase 2 Complete When:
- [ ] Can create Todoist task from dashboard
- [ ] Can mark Todoist task complete
- [ ] Can create quick note to Obsidian
- [ ] All mutations update cache immediately

## Risk Mitigation

### Potential Issues
1. **API Rate Limits:** Use aggressive caching, respect rate limits
2. **Large Obsidian Vaults:** Limit to 20 most recent files
3. **Slow API Responses:** Implement timeouts, show partial data
4. **API Authentication Changes:** Version lock API docs, monitor changelogs

### Contingency Plans
- If PlanToEat API is difficult, defer to Phase 3
- If Trello adds complexity, make fully optional
- If HTMX is limiting, switch to vanilla JS incrementally

## Next Steps
1. Run through "Getting Started Checklist" from spec
2. Begin with Step 1: Project Setup
3. Implement features sequentially following phase order
4. Test continuously with real data
5. Iterate based on daily usage feedback