Skip to content

Latest commit

 

History

History
489 lines (402 loc) · 14.6 KB

roadmap.md

File metadata and controls

489 lines (402 loc) · 14.6 KB

TODO TUI - Development Roadmap

A terminal-based TODO application with kanban boards, knowledge base, and integrations.

Tech Stack

  • TUI Client: Rust + ratatui + crossterm
  • Backend: Rust + Axum + PostgreSQL
  • Hosting: Self-hosted VPS

Phase 1: Foundation

1.1 Project Setup

  • Initialize Cargo workspace with 3 crates
  • Create .env.example
  • Add .gitignore
  • Add rustfmt.toml and clippy config
  • Write roadmap

1.2 Shared Types (crates/todo-shared/)

  • Task model (id, title, status, description, priority, due_date, time_estimate)
  • User model
  • Workspace model (with roles: owner, admin, editor, reader)
  • Comment model
  • Document model (knowledge base)
  • API request/response types

1.3 Database Schema (migrations/)

  • Users & authentication tables
  • Workspaces & membership (with roles)
  • Task statuses (kanban columns)
  • Tasks table with all fields
  • Comments table
  • Tags table
  • Documents table (ltree for hierarchy)
  • Trigram search indexes (pg_trgm for multilingual search)
  • Integration settings tables

1.4 Basic Backend (crates/todo-server/)

  • Axum app skeleton with config
  • Database connection pool (SQLx)
  • Error handling infrastructure
  • Auth endpoints (register, login, JWT)
  • Auth middleware
  • Refresh token handling

1.5 Basic TUI (crates/todo-tui/)

  • Terminal setup/teardown
  • Basic app state structure
  • Event handling loop
  • Basic UI rendering
  • Login view
  • API client skeleton

Phase 2: Core Task Management

2.1 Task API

  • GET /api/v1/workspaces/{wid}/tasks - List tasks
  • POST /api/v1/workspaces/{wid}/tasks - Create task
  • GET /api/v1/workspaces/{wid}/tasks/{id} - Get task
  • PUT /api/v1/workspaces/{wid}/tasks/{id} - Update task
  • DELETE /api/v1/workspaces/{wid}/tasks/{id} - Delete task
  • PUT /api/v1/workspaces/{wid}/tasks/{id}/move - Move task
  • Status CRUD endpoints

2.2 Kanban TUI

  • KanbanBoard component with columns
  • Column component
  • TaskCard component (with priority indicator and due date)
  • Vim navigation (h/j/k/l)
  • Task selection highlighting
  • Move task between columns (m + h/l)
  • Create task (n key)
  • Delete task (d key)
  • Scroll within columns (with scroll indicators)

2.3 Task Detail

  • TaskDetail side panel
  • Title/description editor
  • Priority selector (lowest/low/medium/high/highest)
  • Due date picker
  • Time estimate input
  • Assignee selector (h/l to cycle through workspace members)
  • Default assignee on task creation (workspace setting override)

2.4 Comments

  • GET /api/v1/workspaces/{wid}/tasks/{id}/comments
  • POST /api/v1/workspaces/{wid}/tasks/{id}/comments
  • PUT /api/v1/workspaces/{wid}/tasks/{id}/comments/{cid}
  • DELETE /api/v1/workspaces/{wid}/tasks/{id}/comments/{cid}
  • Comments list in task detail TUI
  • Add comment with timestamp
  • Create CommentWithUser response type (includes author username)
  • Update comment list endpoint to return CommentWithUser
  • Update TUI to display comments as [timestamp][@username]: content

Phase 3: Search & Filtering

3.1 Search Backend

  • Trigram search with pg_trgm (multilingual, typo-tolerant)
  • GET /api/v1/workspaces/{wid}/search?q=...
  • Search pagination

3.2 Search TUI

  • Search panel (/ command)
  • Real-time search results
  • Navigate and select results
  • Highlight matches

3.3 Filtering & Ordering

  • Filter by: status, priority, assignee, due date, tags
  • Order by: title, due_date, priority, created_at, position
  • Filter bar in kanban view
  • Command mode filters (:filter priority=high)
  • Save filter presets

Phase 4: Workspaces & Multi-user

4.0 User Enhancements

  • Add username field to User model (unique, alphanumeric + underscore)
  • Migration: Add username column to users table
  • Update registration to require username
  • Add email verification flow with one-time code
  • Migration: Add verification fields (is_verified, verification_code, verification_expires_at)
  • POST /api/v1/auth/verify - Verify email with code
  • POST /api/v1/auth/resend-verification - Resend verification code
  • Restrict login to verified users only
  • Update TUI registration to include username input
  • Add email verification screen in TUI

4.1 Workspace API

  • GET /api/v1/workspaces - List user's workspaces
  • POST /api/v1/workspaces - Create workspace
  • GET /api/v1/workspaces/{id} - Get workspace
  • PUT /api/v1/workspaces/{id} - Update workspace
  • DELETE /api/v1/workspaces/{id} - Delete workspace
  • Role-based permissions middleware

4.2 Members & Invitations

  • GET /api/v1/workspaces/{id}/members
  • POST /api/v1/workspaces/{id}/invites - Send invite
  • GET /api/v1/invites/{token} - Get invite details
  • POST /api/v1/invites/{token}/accept - Accept invite
  • PUT /api/v1/workspaces/{id}/members/{uid} - Update role
  • DELETE /api/v1/workspaces/{id}/members/{uid} - Remove member

4.3 Workspace TUI

  • Workspace switcher (Ctrl+W)
  • Member list view
  • Role management UI (for admins/owners)
  • Invite flow

Phase 5: Knowledge Base

5.1 Document Storage

  • Document schema with ltree (hierarchical paths)
  • GET /api/v1/workspaces/{wid}/documents - List tree
  • POST /api/v1/workspaces/{wid}/documents - Create document
  • GET /api/v1/workspaces/{wid}/documents/{id} - Get document
  • PATCH /api/v1/workspaces/{wid}/documents/{id} - Update document
  • DELETE /api/v1/workspaces/{wid}/documents/{id} - Delete (cascade)
  • POST /api/v1/workspaces/{wid}/documents/{id}/move - Move in tree

5.2 Knowledge Base TUI

  • DocumentTree component (collapsible, h/l to expand)
  • DocumentViewer (text with wrapping)
  • DocumentEditor
  • Navigate tree with j/k, expand/collapse with h/l
  • Create/delete documents (n/d keys, Ctrl+K to open KB)

5.3 Task-Document Linking

  • POST /api/v1/workspaces/{wid}/documents/{id}/tasks - Link task
  • GET /api/v1/workspaces/{wid}/documents/{id}/tasks - List linked tasks
  • DELETE /api/v1/workspaces/{wid}/documents/{id}/tasks/{tid} - Unlink
  • GET /api/v1/workspaces/{wid}/tasks/{id}/documents - List linked documents
  • Show linked documents in task detail
  • Show linked tasks in document view

5.4 Document Search

  • Full-text search for documents
  • Unified search (tasks + documents)

Tech Debt & Improvements (Discovered Issues)

Critical: Security

  • Replace CorsLayer::permissive() with specific allowed origins
  • Fix refresh token validation (verify token hash, not just existence)
  • Add rate limiting for auth endpoints (login, verification)
  • Improve email validation (RFC 5322 format)

Critical: Cross-Crate Consistency

  • Add username field to User model (exists in DB, missing in model)
  • Add email_verified, email_verified_at to User model
  • Fix tag_ids type mismatch: String (server) vs Vec<Uuid> (shared)

Critical: TUI Race Conditions

  • Fix token refresh race condition (proactive refresh before expiration)
  • Handle stale state after search/navigation

High: Code Duplication (Backend)

  • Extract check_membership() to shared module (duplicated in 6 handlers)
  • Extract verify_task() to shared module (duplicated in 3 handlers)

High: TUI Refactoring

  • Split app.rs (3754 lines) into modules:
    • auth_handlers.rs
    • dashboard_handlers.rs
    • kb_handlers.rs
    • filter_handlers.rs
  • Fix silent failures (search, tags, members, linked docs)
  • Add proper success notifications (not via set_error())

High: Testing & CI

  • Add unit tests
  • Add integration tests
  • Setup GitHub Actions CI/CD
  • Add cargo-audit for vulnerability scanning

Medium: API Consistency

  • Standardize pagination defaults (50 vs 20)
  • Add request body size limits (DefaultBodyLimit)
  • Add color validation for tags/statuses (#RRGGBB)
  • Standardize HTTP status codes for deletes (204 vs 200)

Medium: UX Fixes

  • Add cascade delete warning for documents
  • Add feedback for invalid date input in filters
  • Standardize keybindings across views

Medium: Documentation

  • Update CLAUDE.md with new fields/migrations
  • Add OpenAPI/Swagger documentation
  • Add database ERD
  • Add setup instructions to README

Low: Nice-to-Have Features

  • Soft deletes (deleted_at) for recovery
  • Audit logging (who changed what)
  • Configurable DB pool size (env var)
  • User profile endpoints (change password, delete account)
  • Expired invites cleanup job
  • Batch task operations
  • Search history (Ctrl+R)
  • Column hide/collapse
  • Task sorting within column
  • Toast notifications

Phase 6: Integrations

6.1 YouTrack Sync

  • YouTrack API client (REST)
  • Field mapping configuration
  • POST /api/v1/workspaces/{wid}/integrations - Configure
  • POST /api/v1/workspaces/{wid}/integrations/youtrack/sync - Trigger sync
  • Bidirectional sync engine
  • Conflict resolution (last-write-wins)
  • Background sync job

6.2 GitHub/GitLab

  • POST /api/v1/webhooks/github - Webhook receiver
  • POST /api/v1/webhooks/gitlab - Webhook receiver
  • Signature verification
  • Extract task reference from PR title/branch (e.g., TODO-123)
  • Auto-update task status:
    • PR opened → "In Review"
    • PR merged → "Done"
  • Store PR link in task external_refs

6.3 Telegram Notifications

  • Telegram bot setup (teloxide)
  • /start command - generate link token
  • Link Telegram chat to user account
  • PUT /api/v1/workspaces/{wid}/notifications/settings
  • Notification triggers:
    • Task assigned
    • Task updated
    • New comment
    • Due date approaching (1 day before)
  • Background notification job

6.4 Claude Code (MCP Research)

  • Research Model Context Protocol compatibility
  • Evaluate if MCP tools can expose task data
  • Prototype if viable
  • Document findings

Phase 7: Polish

7.1 UX Improvements

  • Command palette (Ctrl+P)
  • Help overlay (?)
  • Keyboard shortcut reference
  • Home dashboard with workspace stats
  • ASCII art workspace titles (figlet)
  • Quote of the day
  • Markdown rendering in Knowledge Base
  • Remember last opened workspace
  • Status bar (sync status, workspace, user)
  • Notification toasts
  • Undo/redo for task changes
  • Offline mode (queue changes)

7.2 Performance

  • Database query optimization
  • Add indexes for common queries
  • Lazy loading for large task lists
  • Connection pooling tuning
  • TUI rendering optimization

7.3 Deployment

  • Deployment scripts for VPS
  • Systemd service files
  • Nginx reverse proxy config
  • TLS setup (Let's Encrypt / certbot)
  • Database backup scripts

Vim Keybindings

Normal Mode:
  h/l       - Navigate columns
  j/k       - Navigate tasks
  gg/G      - First/last task
  Enter     - Open task detail
  i         - Insert mode (edit)
  a         - Add comment
  n         - New task
  d         - Delete task
  m + h/l   - Move task to column
  Space     - Toggle done
  /         - Search
  :         - Command mode
  Ctrl+P    - Command palette
  Ctrl+W    - Workspace switcher
  Ctrl+K    - Knowledge base
  ?         - Help
  q         - Quit/close

Insert Mode:
  Esc       - Return to normal
  Ctrl+Enter- Save and exit
  Tab       - Next field
  Shift+Tab - Previous field

Command Mode:
  :w        - Save
  :q        - Quit
  :new      - New task
  :filter   - Apply filter
  :sync     - Trigger sync
  :help     - Show help

Database Schema Overview

-- Core entities
users (id, email, username, password_hash, display_name, is_verified, verification_code, created_at)
workspaces (id, name, slug, owner_id, settings jsonb)
workspace_members (workspace_id, user_id, role)

-- Tasks
task_statuses (id, workspace_id, name, slug, color, position, is_done)
tasks (id, workspace_id, status_id, title, description, priority,
       due_date, time_estimate_minutes, position, created_by, assigned_to,
       external_refs jsonb)
task_comments (id, task_id, user_id, content, created_at)
tags (id, workspace_id, name, color)
task_tags (task_id, tag_id)

-- Knowledge base
documents (id, workspace_id, path ltree, parent_id, title, slug, content)
task_document_links (task_id, document_id)

-- Integrations
workspace_integrations (id, workspace_id, integration_type, config, enabled)
user_notification_settings (user_id, workspace_id, telegram_chat_id, ...)

API Endpoints Summary

Auth

POST   /api/v1/auth/register
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
POST   /api/v1/auth/logout
GET    /api/v1/auth/me
POST   /api/v1/auth/verify
POST   /api/v1/auth/resend-verification

Workspaces

GET    /api/v1/workspaces
POST   /api/v1/workspaces
GET    /api/v1/workspaces/{id}
PUT    /api/v1/workspaces/{id}
DELETE /api/v1/workspaces/{id}
GET    /api/v1/workspaces/{id}/members
POST   /api/v1/workspaces/{id}/invites

Statuses

GET    /api/v1/workspaces/{wid}/statuses
POST   /api/v1/workspaces/{wid}/statuses
PUT    /api/v1/workspaces/{wid}/statuses/{id}
DELETE /api/v1/workspaces/{wid}/statuses/{id}
PUT    /api/v1/workspaces/{wid}/statuses/reorder

Tasks

GET    /api/v1/workspaces/{wid}/tasks
POST   /api/v1/workspaces/{wid}/tasks
GET    /api/v1/workspaces/{wid}/tasks/{id}
PUT    /api/v1/workspaces/{wid}/tasks/{id}
DELETE /api/v1/workspaces/{wid}/tasks/{id}
PUT    /api/v1/workspaces/{wid}/tasks/{id}/move

Comments

GET    /api/v1/workspaces/{wid}/tasks/{id}/comments
POST   /api/v1/workspaces/{wid}/tasks/{id}/comments
PUT    /api/v1/workspaces/{wid}/tasks/{id}/comments/{cid}
DELETE /api/v1/workspaces/{wid}/tasks/{id}/comments/{cid}

Documents

GET    /api/v1/workspaces/{wid}/documents
POST   /api/v1/workspaces/{wid}/documents
GET    /api/v1/workspaces/{wid}/documents/{id}
PATCH  /api/v1/workspaces/{wid}/documents/{id}
DELETE /api/v1/workspaces/{wid}/documents/{id}
POST   /api/v1/workspaces/{wid}/documents/{id}/move
GET    /api/v1/workspaces/{wid}/documents/{id}/tasks
POST   /api/v1/workspaces/{wid}/documents/{id}/tasks
DELETE /api/v1/workspaces/{wid}/documents/{id}/tasks/{tid}
GET    /api/v1/workspaces/{wid}/tasks/{id}/documents

Search

GET    /api/v1/workspaces/{wid}/search?q=...&search_type=all|tasks|documents

Integrations

GET    /api/v1/workspaces/{wid}/integrations
POST   /api/v1/workspaces/{wid}/integrations
POST   /api/v1/workspaces/{wid}/integrations/{type}/sync
POST   /api/v1/webhooks/github
POST   /api/v1/webhooks/gitlab