break-it-down/README.md

# TESSERACT - Task Decomposition Engine

A self-hosted web application for managing deeply nested todo trees with JSON seeding capability. Built for breaking down complex projects into hierarchical, manageable tasks.

## Features

- **Arbitrary-Depth Task Hierarchies**: Create projects with unlimited nesting (Project ’ Task ’ Subtask ’ Sub-subtask ’ ...)
- **Dual View Modes**:
  - **Tree View**: Collapsible hierarchical task tree with inline editing
  - **Kanban Board**: Drag-and-drop status management (Backlog, In Progress, Blocked, Done)
- **JSON Import**: Seed projects from JSON files (perfect for LLM-generated task breakdowns)
- **Real-time CRUD**: Add, edit, delete tasks and subtasks on the fly
- **Dark Cyberpunk UI**: Orange-accented dark theme optimized for focus

## Tech Stack

- **Backend**: FastAPI (Python 3.11+)
- **Database**: SQLite (file-based, zero-config)
- **Frontend**: React + Vite + Tailwind CSS
- **Deployment**: Docker + docker-compose

## Quick Start

### Prerequisites

- Docker and docker-compose installed
- OR: Python 3.11+ and Node.js 18+ for local development

### Option 1: Docker (Recommended)

```bash
# Clone the repository
git clone <your-repo-url>
cd tesseract

# Start the application
docker-compose up -d

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs
```

To stop:
```bash
docker-compose down
```

### Option 2: Local Development

#### Backend Setup

```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

Backend will be available at `http://localhost:8000`

#### Frontend Setup

```bash
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev
```

Frontend will be available at `http://localhost:5173`

## Usage

### Creating Projects

1. Click "New Project" on the home page
2. Enter project name and optional description
3. Click "Create" to start building your task tree

### Building Task Trees

**Tree View:**
- Click "Add Root Task" to create top-level tasks
- Hover over any task to reveal action buttons:
  - **+ (Plus)**: Add a subtask
  - ** (Edit)**: Edit title and status
  - **=Ñ (Trash)**: Delete task and all subtasks
- Click expand/collapse arrows to navigate deep hierarchies

**Kanban View:**
- Drag cards between columns to update status
- Click **+** in any column to add tasks with that status
- Click cards to see subtask counts

### JSON Import

Click "Import JSON" and paste a JSON structure like this:

```json
{
  "project": {
    "name": "Project Lyra",
    "description": "AI assistant project with modular architecture"
  },
  "tasks": [
    {
      "title": "Phase 1: Core Infrastructure",
      "description": "Set up foundational systems",
      "status": "in_progress",
      "subtasks": [
        {
          "title": "Database schema design",
          "status": "done"
        },
        {
          "title": "API endpoint implementation",
          "status": "in_progress",
          "subtasks": [
            {
              "title": "User authentication endpoints",
              "status": "done"
            },
            {
              "title": "Task CRUD endpoints",
              "status": "in_progress"
            }
          ]
        }
      ]
    },
    {
      "title": "Phase 2: Frontend Development",
      "status": "backlog",
      "subtasks": [
        {
          "title": "Component library setup",
          "status": "backlog"
        },
        {
          "title": "State management implementation",
          "status": "backlog"
        }
      ]
    }
  ]
}
```

**JSON Schema:**
- `project.name` (required): Project name
- `project.description` (optional): Project description
- `tasks` (array): Root-level tasks
  - `title` (required): Task title
  - `description` (optional): Markdown-friendly description
  - `status` (optional): One of `backlog`, `in_progress`, `blocked`, `done` (default: `backlog`)
  - `subtasks` (array): Nested subtasks (recursive, unlimited depth)

## API Documentation

Once the backend is running, visit `http://localhost:8000/docs` for interactive API documentation.

### Key Endpoints

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

**Tasks:**
- `GET /api/projects/{id}/tasks` - List all tasks for a project
- `GET /api/projects/{id}/tasks/tree` - Get hierarchical task tree
- `GET /api/projects/{id}/tasks/by-status/{status}` - Filter tasks by status
- `POST /api/tasks` - Create task
- `GET /api/tasks/{id}` - Get task details
- `PUT /api/tasks/{id}` - Update task
- `DELETE /api/tasks/{id}` - Delete task (cascades to subtasks)

**Import:**
- `POST /api/import-json` - Import project + task tree from JSON

## Data Model

```

      Project        
$
 id (PK)            
 name               
 description        
 created_at         
 updated_at         

          
           1:N
          ¼

       Task          
$
 id (PK)            
 project_id (FK)    Ä
 parent_task_id (FK)       Self-referencing
 title                     for nesting
 description              
 status                   
 sort_order               
 created_at               
 updated_at         

```

## Database

SQLite database file (`tesseract.db`) is created automatically on first run.

**Location:**
- Docker: Persisted in named volume `tesseract-db`
- Local: `backend/tesseract.db`

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

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

## Development

### Backend Structure
```
backend/
 app/
    __init__.py
    main.py          # FastAPI app + routes
    database.py      # SQLAlchemy setup
    models.py        # Database models
    schemas.py       # Pydantic schemas
    crud.py          # Database operations
 Dockerfile
 requirements.txt
```

### Frontend Structure
```
frontend/
 src/
    components/
       TreeView.jsx     # Collapsible tree view
       KanbanView.jsx   # Drag-and-drop kanban
    pages/
       ProjectList.jsx  # Project list + import
       ProjectView.jsx  # Project detail page
    utils/
       api.js           # API client
    App.jsx
    main.jsx
    index.css
 Dockerfile
 nginx.conf
 package.json
 tailwind.config.js
```

## Future Enhancements

- [ ] LLM integration for auto-generating task breakdowns
- [ ] Markdown rendering in task descriptions
- [ ] Task duration estimates and progress tracking
- [ ] Export to JSON/CSV
- [ ] Multi-user support with authentication
- [ ] Real-time collaboration
- [ ] Task dependencies and blocking relationships
- [ ] Search and filtering
- [ ] Bulk operations

## License

MIT

## Contributing

Issues and pull requests welcome!