# 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