From dfcf56aa4df7800beea4df992e1c96c5f6db5dd3 Mon Sep 17 00:00:00 2001
From: Drew Galbraith <drew@tiramisu.one>
Date: Wed, 22 Oct 2025 21:30:40 -0700
Subject: [PATCH] Plan for implementing projects.

---
 plan/02_PROJECTS/plan.md | 199 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 plan/02_PROJECTS/plan.md

diff --git a/plan/02_PROJECTS/plan.md b/plan/02_PROJECTS/plan.md
new file mode 100644
index 0000000..df9d265
--- /dev/null
+++ b/plan/02_PROJECTS/plan.md
@@ -0,0 +1,199 @@
+# 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
+```sql
+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
+```sql
+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
+```sql
+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