diff options
Diffstat (limited to 'implementation-plan.md')
| -rw-r--r-- | implementation-plan.md | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/implementation-plan.md b/implementation-plan.md new file mode 100644 index 0000000..502e534 --- /dev/null +++ b/implementation-plan.md @@ -0,0 +1,397 @@ +# 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 |