break-it-down/README.md

# TESSERACT

**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.4-orange)
![License](https://img.shields.io/badge/license-MIT-blue)

## Overview

TESSERACT 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, TESSERACT 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**: Toggle between Tree View (hierarchical) and Kanban Board (status-based)
- **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 status tracking
- **Enhanced Task Creation**: Full-featured forms with all metadata fields upfront
- **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
- **Dark Cyberpunk UI**: Orange-accented dark theme optimized for focus

## 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/tesseract.git
   cd tesseract
   ```

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 Tasks

#### Tree View

**Add Root Task**: Click "+ Add Root Task" button
- Enter title (required)
- Add tags (comma-separated, e.g., "frontend, bug-fix")
- Set time estimate (hours and minutes)
- 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

**Edit Task**: Click the three-dot menu (⋮) on any task
- **Change Status**: Backlog → In Progress → Blocked → Done
- **Set Time Estimate**: Separate hours and minutes inputs
- **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

**Add Task**: Click "+" in any column to create a task with that status

**Move Tasks**: Drag and drop cards between columns to change status

**Edit Tasks**: Use the three-dot menu same as Tree View

### Understanding Time Estimates

TESSERACT 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

TESSERACT 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
{
  "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
            }
          ]
        }
      ]
    }
  ]
}
```

See `example-import.json` for a complete example with v0.1.4 features.

### 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
├─ created_at
└─ updated_at

tasks
├─ id (PK)
├─ project_id (FK → projects.id)
├─ parent_task_id (FK → tasks.id) [self-referencing]
├─ title
├─ description
├─ status (enum: backlog, in_progress, blocked, done)
├─ 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

```
tesseract/
├─ 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
│  │  │  ├─ 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 tesseract-backend:/app/tesseract.db ./backup.db

# Local
cp backend/tesseract.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 be: backlog, in_progress, blocked, done)
- Invalid `estimated_minutes` (must be positive integer)
- Malformed JSON syntax

## Roadmap

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

### v0.2.0 (Planned)
- Nested Kanban view (parent cards split across columns)
- 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/tesseract/issues
- **Discussions**: https://github.com/serversdwn/tesseract/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

---

**TESSERACT** - Decompose complexity, achieve clarity.