From 3bb0ca2e58168b28c5e49763acd25f531fb8a78d Mon Sep 17 00:00:00 2001 From: Peter Stone Date: Tue, 20 Jan 2026 15:27:15 -1000 Subject: Add project documentation Include design system guidelines, Phase 3 roadmap, code quality review, proposed README, and authentication ADR. Co-Authored-By: Claude Opus 4.5 --- docs/PHASE_3_PLAN.md | 51 +++++++++++++++++++++++++++++++++ docs/adr/001-authentication-strategy.md | 35 ++++++++++++++++++++++ docs/code_quality_review.md | 38 ++++++++++++++++++++++++ docs/design_system.md | 45 +++++++++++++++++++++++++++++ docs/proposed_readme.md | 30 +++++++++++++++++++ 5 files changed, 199 insertions(+) create mode 100644 docs/PHASE_3_PLAN.md create mode 100644 docs/adr/001-authentication-strategy.md create mode 100644 docs/code_quality_review.md create mode 100644 docs/design_system.md create mode 100644 docs/proposed_readme.md (limited to 'docs') diff --git a/docs/PHASE_3_PLAN.md b/docs/PHASE_3_PLAN.md new file mode 100644 index 0000000..61bac30 --- /dev/null +++ b/docs/PHASE_3_PLAN.md @@ -0,0 +1,51 @@ +# Phase 3: Interactivity & Write Operations + +**Goal:** Transform the dashboard from a passive read-only viewer into an active command center where users can manage tasks directly. + +## Architectural Alignment +The `internal/api/interfaces.go` file already defines the necessary write contracts (`CreateCard`, `UpdateCard`, `CreateTask`, `CompleteTask`). Phase 3 focuses on implementing these methods and wiring them to the UI. + +## Step 1: Trello Write Operations (Priority) +**Objective:** Enable basic card management within the dashboard. + +* **Backend (`internal/api/trello.go`):** + * Implement `CreateCard(title, listID string) error` + * Implement `UpdateCard(cardID string, updates map[string]interface{}) error` (for moving lists or archiving) +* **Handlers (`internal/handlers/trello.go`):** + * `HandleCreateCard`: Accepts POST data, calls API, returns updated list HTML. + * `HandleMoveCard`: Accepts POST data (new list ID), calls API. + * `HandleCompleteCard`: Archives card or moves to "Done" list. +* **UI (`web/templates/partials/trello-boards.html`):** + * **Add Card:** Simple input + button at the bottom of each list (`hx-post`). + * **Complete:** Checkbox or "Done" button on cards. + * **Drag & Drop:** (Optional for v1) Use `SortableJS` wired to `hx-post` for list changes. + +## Step 2: Todoist Write Operations +**Objective:** Quick task capture and completion. + +* **Backend (`internal/api/todoist.go`):** + * Implement `CreateTask(content string) error` + * Implement `CompleteTask(taskID string) error` +* **Handlers (`internal/handlers/todoist.go`):** + * `HandleCreateTask`: Adds task, returns updated list. + * `HandleCompleteTask`: Marks complete, returns updated list (or empty response to remove element). +* **UI (`web/templates/partials/tasks-tab.html`):** + * **Quick Add:** Input field at top of list (`hx-post`, `hx-target="#task-list"`, `hx-swap="prepend"`). + * **Completion:** Checkbox on task items (`hx-post`, `hx-target="closest li"`, `hx-swap="delete"`). + +## Step 3: Unified "Quick Add" (Power User Feature) +**Objective:** A single entry point for all tasks. + +* **Concept:** Global input bar (e.g., triggered by `CMD+K` or always visible). +* **Logic:** + * Parses input text for keywords/tags. + * `"Buy milk #groceries"` -> Routes to Todoist. + * `"Fix bug #work"` -> Routes to Trello. + * `"Idea: New app"` -> Routes to Obsidian (Append to Daily Note - *Future Scope*). +* **Implementation:** + * `HandleQuickAdd`: Parses string, delegates to appropriate Service, returns success toast. + +## Technical Strategy +* **HTMX:** Use `hx-post`, `hx-target`, and `hx-swap` for seamless updates. +* **Optimistic UI:** Where possible, remove/add items from DOM immediately while request processes (using HTMX `hx-on` or CSS transitions). +* **Error Handling:** If API call fails, revert UI state and show `error-banner`. diff --git a/docs/adr/001-authentication-strategy.md b/docs/adr/001-authentication-strategy.md new file mode 100644 index 0000000..e3610f3 --- /dev/null +++ b/docs/adr/001-authentication-strategy.md @@ -0,0 +1,35 @@ +# ADR 001: Authentication Strategy + +## Status +Accepted + +## Context +The application is being prepared for deployment to a public server. Currently, it has no authentication mechanism. We need to secure the application to prevent unauthorized access to personal task data (Todoist, Trello, etc.). + +## Decision +We will implement **Session-Based Authentication** using server-side sessions stored in SQLite. + +### Technical Details: +1. **Session Management:** Use `alexedwards/scs` (v2) for session management. + * It provides a robust, secure implementation of session cookies. + * It supports SQLite as a backing store, simplifying infrastructure (no Redis needed). +2. **User Storage:** Create a `users` table in the existing SQLite database. + * Columns: `id`, `username`, `password_hash`, `created_at`. +3. **Password Hashing:** Use `bcrypt` (via `golang.org/x/crypto/bcrypt`) for hashing passwords. +4. **Middleware:** Implement a middleware function to protect routes. + * Public routes: `/login`, `/static/*`. + * Protected routes: `/`, `/api/*`, etc. + +## Consequences +* **Pros:** + * Simple architecture (keeps everything in SQLite). + * Standard, well-understood security model. + * `scs` handles cookie security (HttpOnly, Secure, SameSite) automatically. +* **Cons:** + * Stateful (sessions in DB), but acceptable for this scale. + * Requires managing a user table and password resets (though we will start with manual user creation). + +## Alternatives Considered +* **Basic Auth:** Too simple, poor UX (browser popup), hard to log out. +* **OAuth (Google/GitHub):** Overkill for a single-user/small-group app initially. Adds external dependencies and configuration complexity. +* **JWT (Stateless):** Adds complexity with token revocation and refresh tokens. Session-based is simpler for a server-rendered app. diff --git a/docs/code_quality_review.md b/docs/code_quality_review.md new file mode 100644 index 0000000..5ee363d --- /dev/null +++ b/docs/code_quality_review.md @@ -0,0 +1,38 @@ +# Code Quality Review + +## Overview +This review focuses on the simplicity, security, and maintainability of the Task Dashboard codebase. The project follows a standard Go project structure with clear separation of concerns between handlers, API clients, storage, and models. + +## Simplicity & Maintainability + +### Strengths +1. **Clear Structure**: The `internal` package is well-organized into `api`, `config`, `handlers`, `models`, and `store`. This makes navigation intuitive. +2. **Standard Library Usage**: The project relies heavily on the Go standard library (`net/http`, `encoding/json`, `database/sql`, `html/template`), reducing external dependencies and keeping the codebase lightweight. +3. **Concurrency Management**: `aggregateData` in `handlers.go` effectively uses `sync.WaitGroup` and `sync.Mutex` to fetch data from multiple sources in parallel. The Trello client (`api/trello.go`) implements a semaphore pattern (limit of 5 concurrent requests) to limit concurrent requests, preventing rate limiting issues. +4. **Configuration**: `config/config.go` provides a centralized way to load and validate configuration from environment variables. + +### Areas for Improvement +1. **Error Handling in Goroutines**: In `aggregateData`, errors from goroutines are appended to a `data.Errors` slice. While this prevents the entire request from failing, it might mask critical issues if not monitored. Consider adding structured logging or metrics for these errors. +2. **Template Parsing**: Templates are parsed in `New` handler. In a development environment, it might be beneficial to re-parse templates on each request (or use a flag) to avoid restarting the server for template changes. +3. **Hardcoded Limits**: Some limits (e.g., fetching 20 notes in `HandleGetNotes`) are hardcoded. These could be moved to configuration. + +## Security + +### Strengths +1. **SQL Injection Prevention**: The `store/sqlite.go` implementation consistently uses parameterized queries (`?` placeholders) for all SQL operations (including `INSERT OR REPLACE`), effectively mitigating SQL injection risks. +2. **XSS Protection**: The use of `html/template` ensures that data rendered in HTML is automatically escaped, protecting against Cross-Site Scripting (XSS) attacks. +3. **Secret Management**: API keys and tokens are loaded from environment variables via `config/config.go`, ensuring secrets are not hardcoded in the source code. +4. **Database Locking**: The SQLite store enables WAL mode and sets `MaxOpenConns(1)` to handle concurrency safely and avoid "database is locked" errors. + +### Areas for Improvement +1. **CSRF Protection**: There is no explicit CSRF protection middleware visible in the handlers. Since the app performs state-changing actions (creating/completing tasks), adding a CSRF token to forms would be a security enhancement. +2. **Input Validation**: While basic validation exists (checking for empty fields in `HandleCreateCard` and `HandleCreateTask`), more rigorous validation on input length and format could be added. +3. **HTTPS**: The server runs on HTTP by default. For production deployment, ensuring it runs behind a reverse proxy with TLS (like Nginx or Caddy) is essential. + +## Testing +The project includes test files (`sqlite_test.go`), indicating a commitment to testing. +* **Store Tests**: The `sqlite_test.go` file covers basic CRUD operations for notes, tasks, and cards, including specific tests for `DeleteTask` and `DeleteCard`. It also includes a test case specifically designed to verify protection against SQL injection (`TestGetNotes_SQLInjectionAttempt`). +* **Missing Tests**: A more comprehensive test suite covering handlers and API clients with mocks is missing and would further ensure reliability. + +## Conclusion +The codebase is clean, secure, and follows Go best practices. It balances simplicity with necessary complexity (concurrency) well. Addressing the minor improvements in error handling and security (CSRF) would make it even more robust. diff --git a/docs/design_system.md b/docs/design_system.md new file mode 100644 index 0000000..5c20f41 --- /dev/null +++ b/docs/design_system.md @@ -0,0 +1,45 @@ +# Design System: Glassmorphism Overhaul + +## Core Philosophy +* **Light & Airy:** Use a pastel mesh gradient background to provide depth. +* **Glass Surfaces:** Content resides on semi-transparent, blurred layers (`backdrop-filter`). +* **Soft Borders:** 1px white borders with low opacity to define edges without harsh lines. +* **Floating Depth:** Use shadows to lift elements off the background. + +## Color Palette +* **Background:** Linear Gradient (Top-Left to Bottom-Right) + * From: `indigo-100` (#e0e7ff) + * Via: `purple-100` (#f3e8ff) + * To: `pink-100` (#fce7f3) +* **Surface (Glass):** + * Background: `rgba(255, 255, 255, 0.7)` + * Border: `rgba(255, 255, 255, 0.5)` +* **Text:** + * Primary: `gray-900` + * Secondary: `gray-600` + * Accent: `indigo-600` + +## Components + +### Base +* **Body:** `bg-gradient-to-br from-indigo-100 via-purple-100 to-pink-100 min-h-screen` + +### Cards (`.card`) +* **Style:** + * `bg-white/70` (70% opacity white) + * `backdrop-blur-lg` (Large blur) + * `border border-white/50` + * `shadow-xl` + * `rounded-2xl` (More rounded than before) + +### Navigation (`.tab-button`) +* **Active State:** + * Instead of a bottom border, use a "pill" background. + * `bg-white/50` + * `shadow-sm` + * `text-indigo-700` + * `rounded-lg` + +### Typography +* **Font:** Inter (Existing) +* **Headings:** Dark Gray (`gray-900`), slightly tighter tracking. diff --git a/docs/proposed_readme.md b/docs/proposed_readme.md new file mode 100644 index 0000000..1fa9f97 --- /dev/null +++ b/docs/proposed_readme.md @@ -0,0 +1,30 @@ +# Task Dashboard + +## Project Goals +The Task Dashboard aims to provide a unified, single-pane-of-glass view of your daily obligations and resources. It aggregates data from multiple specialized tools into one streamlined interface, allowing you to: +* **Centralize Information:** View tasks, notes, and meal plans from Todoist, Trello, Obsidian, and PlanToEat in one place. +* **Increase Efficiency:** Quickly assess your day's priorities without context-switching between multiple applications. +* **Facilitate Action:** Perform key actions like completing tasks and creating new items directly from the dashboard. + +## Current Status +The project is a functional web application built with Go. +* **Backend:** Written in Go (1.21+), utilizing `chi` for routing. It features a clean architecture with decoupled service integrations. +* **Frontend:** Server-side rendered HTML templates styled with Tailwind CSS. +* **Integrations:** + * **Todoist:** Full integration for fetching and managing tasks. + * **Trello:** Integration for viewing and managing board cards. + * **Obsidian:** Read-only access to local markdown notes. + * **PlanToEat:** Retrieval of meal planning data. +* **Storage:** SQLite is used for robust caching of external API responses to improve performance and reduce rate limiting. +* **Entry Point:** The application entry point is located at `cmd/dashboard/main.go`. + +## Future Plans +* **Deepened Integrations:** Expand capabilities to include editing notes and more complex project management features. +* **Interactive UI:** Enhance the frontend responsiveness and interactivity, potentially leveraging HTMX for dynamic updates without full page reloads. +* **Resilience & Observability:** Improve error handling, logging, and metrics to ensure long-term reliability. + +## Architectural Principles +1. **Aggregation:** The system is designed primarily as an aggregator, normalizing data from various external sources into a cohesive internal model (`DashboardData`). +2. **Decoupling:** External services are abstracted behind strict interfaces (`internal/api/interfaces.go`), allowing for easy substitution, testing, and mocking. +3. **Performance via Caching:** A heavy emphasis on caching (via SQLite) ensures the dashboard remains fast and responsive, even when external APIs are slow or unavailable. +4. **Simplicity:** The stack prefers simple, proven technologies (Go templates, Tailwind, SQLite) over complex single-page application frameworks to maintain ease of maintenance and deployment. -- cgit v1.2.3