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)

# 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:

docker-compose down

Option 2: Local Development

Backend Setup

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

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:

{
  "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:

# 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!