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

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

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

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 be: backlog, in_progress, blocked, done)
• Invalid estimated_minutes (must be positive integer)
• Malformed JSON syntax

Roadmap

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