TESSERACT

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

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

   git clone https://github.com/serversdwn/tesseract.git
   cd tesseract
   

2. Start the application

   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

# 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

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:

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

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
│  │  │  ├─ 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

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

cd frontend
npm install
npm run dev

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

Database Management

Backup:

# Docker
docker cp tesseract-backend:/app/tesseract.db ./backup.db

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

Schema Changes: For schema updates in development:

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:

docker-compose down -v  # Removes volumes
docker-compose up --build

Port Conflicts

If ports 3000 or 8000 are in use, modify docker-compose.yml:

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 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/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.