captains-log/plan/02_PROJECTS/plan.md

Project-Based Organization Implementation Plan

Phase Overview

This plan implements project-based organization with a clean folder/project hierarchy:

• Folders: Organizational containers for projects (can be reordered)
• Projects: Work containers that hold tasks (can belong to folders or exist at root)
• Tasks: Belong to zero or one project (never directly to folders)

Backend Implementation

1. Database Schema Changes

• New Tables:
  • folders table: id, name, color, sort_order, created_at, updated_at
  • projects table: id, name, description, color, due_date, status, folder_id (nullable), sort_order, created_at, updated_at
• Schema Updates:
  • Add project_id field to existing tasks table (nullable foreign key)
  • Database indexes for efficient querying

2. Backend Models & Services

• FolderModel (backend/src/models/folder.rs):
  • CRUD operations for folders
  • Reordering methods for sort_order management
• ProjectModel (backend/src/models/project.rs):
  • CRUD operations with folder relationship
  • Methods for reordering within folders and at root level
  • Query methods for folder contents
• Updated TaskModel (backend/src/models/task.rs):
  • Add project_id field and foreign key constraint
  • Project relationship methods
• API Services:
  • folders.rs - Folder CRUD and reordering endpoints
  • projects.rs - Project CRUD, folder assignment, reordering
  • Updated tasks.rs - Project filtering and assignment

3. Database Migrations

• Create folders table
• Create projects table with folder foreign key
• Add project_id to tasks table
• Set up proper indexes and constraints

Frontend Implementation

1. Data Models & Types

• Folder Types (frontend/app/types/folder.ts):
  • Folder interface, CreateFolderRequest, UpdateFolderRequest
• Project Types (frontend/app/types/project.ts):
  • Project interface with folder_id field
  • ProjectStatus enum, CRUD request types
• Updated Task Types (frontend/app/types/task.ts):
  • Add project_id field to Task interface

2. Sidebar & Navigation

• ProjectSidebar (frontend/app/components/ProjectSidebar.tsx):
  • Hierarchical display: Folders → Projects → (Root Projects)
  • Drag-and-drop for both folder and project reordering
  • Inline creation forms for folders and projects
  • Collapsible folder sections
• FolderSection (frontend/app/components/FolderSection.tsx):
  • Individual folder with contained projects
  • Folder editing and project management

3. Project Management

• ProjectForm (frontend/app/components/ProjectForm.tsx):
  • Create/edit projects with folder assignment
  • 16-color palette, due dates, status selection
• FolderForm (frontend/app/components/FolderForm.tsx):
  • Simple folder creation/editing (name, color)

4. Updated Task Components

• Enhanced TaskList with Project column
• Updated TaskForm with project selection dropdown
• Project filtering throughout the UI

5. Routes & State Management

• New Routes:
  • /projects - Projects overview
  • /projects/{id} - Project detail page
  • /folders/{id} - Folder contents view
• State Hooks:
  • useFolders.ts, useProjects.ts, updated useTasks.ts
• API Integration:
  • Folder and project API clients

Implementation Order

Phase 1: Backend Foundation

1. Create folders and projects tables (migrations)
2. Implement FolderModel and ProjectModel
3. Add project_id to TaskModel
4. Create API endpoints for folders and projects
5. Unit tests for new functionality

Phase 2: Frontend Core

1. Implement folder and project types
2. Create basic ProjectSidebar (no drag-drop yet)
3. Add project column to TaskList
4. Update TaskForm with project selection
5. Basic project/folder CRUD forms

Phase 3: Advanced Features

1. Drag-and-drop reordering in sidebar
2. Project and folder detail pages
3. Hierarchical project creation flows
4. Project filtering and search
5. Mobile responsive sidebar

Phase 4: Polish & Integration

1. Project color theming throughout UI
2. Performance optimization
3. Enhanced UX for project management
4. Integration testing
5. Migration tools for existing data

Data Relationships

folders (1) → (many) projects
projects (1) → (many) tasks
folders (no direct relationship) tasks

This clean separation ensures tasks only belong to projects, while folders serve purely as organizational containers for projects.

Technical Implementation Details

Database Schema

Folders Table

CREATE TABLE folders (
    id UUID PRIMARY KEY NOT NULL,
    name VARCHAR NOT NULL,
    sort_order INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Projects Table

CREATE TABLE projects (
    id UUID PRIMARY KEY NOT NULL,
    name VARCHAR NOT NULL,
    description TEXT,
    color VARCHAR(7), -- hex color code
    due_date DATE,
    status TEXT CHECK(status IN ('active', 'done', 'backlog')) DEFAULT 'active',
    folder_id UUID REFERENCES folders(id) ON DELETE SET NULL,
    sort_order INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Tasks Table Update

ALTER TABLE tasks ADD COLUMN project_id UUID REFERENCES projects(id) ON DELETE SET NULL;

Color Palette

16-color palette for folders and projects:

• Primary Blues: #1976d2, #0288d1, #0097a7
• Greens: #388e3c, #689f38, #7cb342
• Oranges/Reds: #f57c00, #ff5722, #d32f2f
• Purples: #7b1fa2, #512da8, #303f9f
• Neutrals: #455a64, #616161, #757575, #424242

API Endpoints

Folders

• GET /api/folders - List all folders with projects
• POST /api/folders - Create folder
• PUT /api/folders/{id} - Update folder
• DELETE /api/folders/{id} - Delete folder
• PUT /api/folders/reorder - Reorder folders

Projects

• GET /api/projects - List all projects
• GET /api/projects?folder_id={id} - List projects in folder
• POST /api/projects - Create project
• PUT /api/projects/{id} - Update project
• DELETE /api/projects/{id} - Delete project
• PUT /api/projects/reorder - Reorder projects within folder/root

Tasks (Updated)

• GET /api/tasks?project_id={id} - List tasks in project
• Task CRUD operations include project_id field

Migration Strategy

1. Existing tasks remain unassigned (project_id = NULL)
2. Users can create folders and projects
3. Users can assign existing tasks to projects
4. No data loss during migration
5. Backwards compatibility maintained

Testing Strategy

• Unit tests for all model methods
• API integration tests with Hurl
• Frontend component tests
• End-to-end project workflow tests