break-it-down/README.md

# Break It Down - BIT

**Task Decomposition Engine** - A self-hosted web application for managing deeply nested todo trees with advanced time tracking and project planning capabilities.

![Version](https://img.shields.io/badge/version-0.1.6-orange)
![License](https://img.shields.io/badge/license-MIT-blue)

## Overview

Break It Down is designed for complex project management where tasks naturally decompose into hierarchical structures. Whether you're breaking down software projects, research tasks, or multi-phase initiatives, BIT helps you visualize, track, and manage work at any level of granularity.

### Key Features

- **Arbitrary-Depth Nesting**: Create tasks within tasks within tasks - no limits on hierarchy depth
- **Dual View Modes**:
  - **Tree View**: Hierarchical collapsible tree with full nesting
  - **Nested Kanban**: Status-based board where parent tasks appear in multiple columns
- **Dynamic Status Workflows** (v0.1.6):
  - Customizable per-project status workflows
  - Drag-and-drop status reordering
  - Add, rename, or delete statuses with validation
  - Project Settings modal for easy configuration
- **Intelligent Time Tracking**:
  - Leaf-based time calculation (parent times = sum of descendant leaf tasks)
  - Automatic exclusion of completed tasks from time estimates
  - Shows remaining work, not total estimated work
  - Auto-complete parents when all children are done
- **Rich Metadata**: Tags, time estimates, priority flags, and customizable status tracking
- **Enhanced Task Creation**:
  - Full-featured forms with all metadata fields upfront
  - Status selector in task creation forms
  - Subtask creation directly in Kanban view
- **LLM Integration**: Import JSON task trees generated by AI assistants
- **Real-Time Search**: Find tasks across projects with filtering
- **Self-Hosted**: Full data ownership and privacy

## Tech Stack

- **Backend**: Python FastAPI + SQLAlchemy ORM
- **Database**: SQLite (easy to backup, portable)
- **Frontend**: React + Tailwind CSS
- **Deployment**: Docker + Docker Compose
- **Web Server**: Nginx (reverse proxy)

## Quick Start

### Prerequisites

- Docker
- Docker Compose
- Git

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/serversdwn/break-it-down.git
   cd break-it-down
   ```

2. **Start the application**
   ```bash
   docker-compose up --build
   ```

3. **Access the app**
   - Frontend: `http://localhost:3000`
   - Backend API: `http://localhost:8000`
   - API Docs: `http://localhost:8000/docs`

### Stopping the Application

```bash
# Stop containers (preserves data)
docker-compose down

# Stop and remove data
docker-compose down -v
```

## Usage Guide

### Creating a Project

1. Click "New Project" on the home page
2. Enter a project name and optional description
3. Click "Create"

### Managing Project Settings

Click the **⚙️ Settings** button in the project header to access:

**Status Workflow Management:**
- **View Statuses**: See all current statuses in order with task counts
- **Reorder**: Drag and drop statuses to change Kanban column order
- **Add Status**: Click "+ Add Status" to create a new custom status
- **Rename**: Click any status name to edit inline (auto-formats to lowercase_with_underscores)
- **Delete**: Click trash icon to remove unused statuses
  - Cannot delete statuses that have tasks (shows warning with count)
  - Cannot delete the last remaining status
- **Save**: Click "Save Changes" to apply your workflow

**Default Statuses**: `backlog`, `in_progress`, `on_hold`, `done`

### Managing Tasks

#### Tree View

**Add Root Task**: Click "+ Add Root Task" button
- Enter title (required)
- Add description (optional)
- Add tags (comma-separated, e.g., "frontend, bug-fix")
- Set time estimate (hours and minutes)
- **Select status** (defaults to "backlog")
- Choose flag color (8 colors or none)

**Add Subtask**: Click the "+" icon on any task
- Same full-featured form as root tasks
- Creates a child of the selected task
- Status selector available

**Edit Task**: Click the three-dot menu (⋮) on any task
- **Change Status**: Choose from your project's custom statuses
- **Set Time Estimate**: Separate hours and minutes inputs
- **Edit Description**: Multi-line text area
- **Edit Tags**: Comma-separated list
- **Set Flag Color**: 8 colors available
- **Edit Title**: Rename the task
- **Delete Task**: Cascades to all subtasks

**Expand/Collapse**: Click chevron icon to show/hide subtasks

#### Kanban View (Nested)

The Kanban board displays tasks in a nested hierarchy while maintaining status-based columns:

**Parent Cards**:
- Appear in **every column** where they have subtasks
- Display "X of Y subtasks in this column" counter
- Have distinct styling (thick orange border, bold title)
- Click chevron to expand/collapse and see children in that column
- Cannot be dragged (only leaf tasks are draggable)
- Click "+" button to add subtasks directly

**Leaf Tasks**:
- Appear only in their status column
- Fully draggable between columns
- Standard card styling
- Click "+" button to add subtasks (converts to parent)

**Add Root Task**: Click "+" in any column header
- Opens TaskForm with status pre-selected to that column
- All metadata fields available (tags, time, flag, description)

**Add Subtask**: Click "+" button on any task card (appears on hover)
- Opens TaskForm below the parent card
- Status defaults to current column
- Automatically expands parent after creation

**Move Tasks**: Drag and drop leaf task cards between columns

**Edit Tasks**: Use the three-dot menu on any card (parent or leaf)

**Example**: A project with backend (2 tasks in backlog, 1 in progress) and frontend (1 in done) will show the project card in all three columns with appropriate counts.

### Understanding Time Estimates

Break It Down uses **leaf-based time calculation** for accurate project planning:

- **Leaf Tasks** (no subtasks): Display shows their own time estimate
- **Parent Tasks** (have subtasks): Display shows sum of ALL descendant leaf tasks
- **Completed Tasks**: Time is crossed out (~~strikethrough~~) and excluded from parent calculations
- **Auto-Update**: Parent times update automatically as you mark tasks done
- **Auto-Complete**: When all child tasks are marked "done", the parent automatically becomes "done"

**Example:**
```
Project: Build Feature (est: 5h) → Shows: 3h 30m
├─ Backend (est: 2h) → Shows: 1h 30m
│  ├─ API Endpoint (1h) → Shows: 1h [LEAF]
│  └─ Tests (30m - DONE) → Shows: ~~30m~~ [LEAF, excluded]
└─ Frontend (est: 3h) → Shows: 2h
   ├─ Component (1h) → Shows: 1h [LEAF]
   └─ Styling (1h - DONE) → Shows: ~~1h~~ [LEAF, excluded]

Remaining work: 3h 30m (not 10h!)
```

### Using Tags and Flags

**Tags**: Categorize tasks
- Enter as comma-separated values
- Display as orange badges on task cards
- Searchable via search bar
- Examples: "frontend", "bug-fix", "priority", "research"

**Flags**: Visual priority indicators
- 8 colors: Red, Orange, Yellow, Green, Blue, Purple, Pink, None
- Quick visual scanning for important tasks
- Color-coded flag icons on tasks

### JSON Import

Break It Down can import task hierarchies from JSON files, making it perfect for LLM-generated project breakdowns.

1. Click "Import JSON" on a project
2. Upload a file matching this structure:

```json
{
  "project": {
    "name": "My Project",
    "description": "Project description",
    "statuses": ["backlog", "in_progress", "on_hold", "done"]
  },
  "tasks": [
    {
      "title": "Main Task",
      "description": "Task description",
      "status": "backlog",
      "estimated_minutes": 120,
      "tags": ["coding", "backend"],
      "flag_color": "red",
      "subtasks": [
        {
          "title": "Subtask 1",
          "estimated_minutes": 60,
          "tags": ["api"],
          "subtasks": [
            {
              "title": "Sub-subtask",
              "estimated_minutes": 30
            }
          ]
        }
      ]
    }
  ]
}
```

**Notes:**
- `project.statuses` is optional (defaults to: backlog, in_progress, on_hold, done)
- `status` must match one of the project's statuses
- See `example-import.json` for a complete example

### Search

Use the search bar in the header to find tasks across all projects:
- Type to search (300ms debounce)
- Filter by specific projects using the project selector
- Click any result to jump to that project
- Search includes title, description, and tags

## Architecture

### Database Schema

```
projects
├─ id (PK)
├─ name
├─ description
├─ statuses (JSON array, default: ["backlog", "in_progress", "on_hold", "done"])
├─ created_at
└─ updated_at

tasks
├─ id (PK)
├─ project_id (FK → projects.id)
├─ parent_task_id (FK → tasks.id) [self-referencing]
├─ title
├─ description
├─ status (String, validated against project.statuses)
├─ sort_order
├─ estimated_minutes (Integer)
├─ tags (JSON array)
├─ flag_color (String)
├─ created_at
└─ updated_at
```

### API Endpoints

**Projects:**
- `GET /api/projects` - List all projects
- `POST /api/projects` - Create project
- `GET /api/projects/{id}` - Get project
- `PUT /api/projects/{id}` - Update project
- `DELETE /api/projects/{id}` - Delete project

**Tasks:**
- `GET /api/projects/{id}/tree` - Get hierarchical task tree
- `GET /api/projects/{id}/tasks` - Get flat task list
- `POST /api/projects/{id}/import` - Import JSON task tree
- `GET /api/tasks/{id}` - Get specific task
- `POST /api/tasks` - Create task
- `PUT /api/tasks/{id}` - Update task (auto-completes parents)
- `DELETE /api/tasks/{id}` - Delete task (cascades to subtasks)

**Search:**
- `GET /api/search?query={q}&project_ids={ids}` - Search tasks

## Development

### Project Structure

```
break-it-down/
├─ backend/
│  ├─ app/
│  │  ├─ main.py          # FastAPI application
│  │  ├─ models.py        # SQLAlchemy models
│  │  ├─ schemas.py       # Pydantic schemas
│  │  ├─ crud.py          # Database operations
│  │  └─ database.py      # DB connection
│  ├─ Dockerfile
│  └─ requirements.txt
├─ frontend/
│  ├─ src/
│  │  ├─ components/
│  │  │  ├─ TreeView.jsx          # Hierarchical tree
│  │  │  ├─ KanbanView.jsx        # Status board
│  │  │  ├─ ProjectSettings.jsx   # Status workflow management
│  │  │  ├─ TaskMenu.jsx          # Three-dot menu
│  │  │  ├─ TaskForm.jsx          # Enhanced creation form
│  │  │  └─ SearchBar.jsx         # Search component
│  │  ├─ pages/
│  │  │  ├─ ProjectList.jsx       # Project list
│  │  │  └─ ProjectView.jsx       # Project detail
│  │  ├─ utils/
│  │  │  ├─ api.js                # API client
│  │  │  └─ format.js             # Time/tag formatting
│  │  └─ App.jsx
│  ├─ Dockerfile
│  └─ package.json
├─ nginx/
│  └─ nginx.conf
├─ docker-compose.yml
├─ example-import.json
├─ CHANGELOG.md
└─ README.md
```

### Local Development

#### Backend

```bash
cd backend
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

#### Frontend

```bash
cd frontend
npm install
npm run dev
```

Frontend will be available at `http://localhost:5173` (Vite default)

### Database Management

**Backup:**
```bash
# Docker
docker cp bit-backend:/app/bit.db ./backup.db

# Local
cp backend/bit.db ./backup.db
```

**Schema Changes:**
For schema updates in development:
```bash
docker-compose down -v  # Removes volumes
docker-compose up --build  # Recreates with new schema
```

## Troubleshooting

### Database Errors

If you see "no such column" errors after an update:
```bash
docker-compose down -v  # Removes volumes
docker-compose up --build
```

### Port Conflicts

If ports 3000 or 8000 are in use, modify `docker-compose.yml`:
```yaml
services:
  frontend:
    ports:
      - "3001:80"  # Change 3000 to 3001
  backend:
    ports:
      - "8001:8000"  # Change 8000 to 8001
```

### Import Failures

Ensure JSON structure matches schema. Common issues:
- Missing required `title` field
- Invalid `status` values (must match project's statuses)
- Invalid `estimated_minutes` (must be positive integer)
- Malformed JSON syntax
- Status not in project's status list (import validates against project.statuses)

## Roadmap

See [CHANGELOG.md](CHANGELOG.md) for version history.

### v0.2.0 (Planned)
- Task dependencies and blocking relationships
- Due dates and calendar view
- Progress tracking (% complete)
- Task templates
- Bulk operations

### v0.3.0 (Planned)
- Multi-user support with authentication
- Real-time collaboration
- Activity history and audit logs
- Export to various formats (Markdown, PDF)
- Mobile-responsive improvements
- Database migration tooling (Alembic)

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Code Style

- **Backend**: Follow PEP 8 (Python)
- **Frontend**: Use ESLint configuration
- **Commits**: Use conventional commit messages

## License

MIT License - see LICENSE file for details

## Support

- **Issues**: https://github.com/serversdwn/break-it-down/issues
- **Discussions**: https://github.com/serversdwn/break-it-down/discussions

## Acknowledgments

- Inspired by the need for better hierarchical task management
- Built with modern web technologies and best practices
- Designed for self-hosting and data ownership

---

**Break It Down (BIT)** - Decompose complexity, achieve clarity.