Task Blaster

A modern, full-stack project management application specifically designed for agentic software development workflows. Built with Next.js 15, TypeScript, PostgreSQL, and Drizzle ORM, Task Blaster facilitates seamless collaboration between human developers and AI agents using intuitive Kanban-style project management.

🤖 Agentic Development Focus

Task Blaster is purpose-built to support modern AI-assisted software development where autonomous agents work alongside human developers. The platform provides structured project management that enables:

• Agent-Human Collaboration: Seamless task handoffs between AI agents and human developers
• Structured Workflows: Kanban boards that accommodate both automated and manual development processes
• Rich Documentation: Markdown support for detailed specifications that agents can understand and act upon
• Project Codes: Unique identifiers that help agents reference and organize work across projects
• Visual Progress Tracking: Clear status indicators that both humans and agents can interpret

🚀 Features

• Kanban Board: Drag-and-drop task management across multiple columns (Todo, In Progress, In Review, Done)
• Human-Readable Task IDs: Auto-generated task identifiers (e.g., PROJ-1, PROJ-2) for easy reference
• Task Lifecycle Tracking: Automatic timestamps for task creation, start, and completion dates
• Project Management: Create and manage multiple projects with team leaders and unique codes
• User Management: Assign tasks to team members with type-ahead search
• Image Attachments: Upload, view, and delete images attached to tasks with thumbnail previews
• Markdown Support: Rich text descriptions for tasks with formatting toolbar
• Real-time Updates: Optimistic UI updates with persistent database storage
• Responsive Design: Full-width kanban columns that adapt to any screen size
• Dark/Light Theme: Toggle between themes for better user experience
• Keyboard Navigation: Full keyboard accessibility support
• Efficient Drag & Drop: Sparse numbering algorithm for optimal performance with blocked task support

🛠️ Tech Stack

• Frontend: Next.js 15, React 19, TypeScript
• UI Components: shadcn/ui, Tailwind CSS
• Database: PostgreSQL with Drizzle ORM
• Drag & Drop: @dnd-kit/core and @dnd-kit/sortable
• Markdown Editor: @uiw/react-md-editor
• Containerization: Docker & Docker Compose

📋 Prerequisites

• Docker and Docker Compose
• Node.js 22+ (for local development)
• Git

🐳 Quick Start with Docker

1. Clone the Repository

git clone <repository-url>
cd task-blaster

2. Start the Application

# Start all services (PostgreSQL + Next.js)
docker-compose up -d

# Or start in the foreground to see logs
docker-compose up

3. Run Database Migrations

# Run migrations to create database schema
docker-compose exec nextjs npm run db:migrate

4. Seed Test Data

# Option 1: Complete reset and seed all data (recommended for fresh start)
docker-compose exec nextjs npx tsx scripts/reset-and-seed.ts

# Option 2: Seed all data without clearing existing data
docker-compose exec nextjs npx tsx scripts/seed-all.ts

Or seed data components individually:

# Seed users only
docker-compose exec nextjs npx tsx scripts/seed-users.ts

# Seed projects only (requires users first)
docker-compose exec nextjs npx tsx scripts/seed-projects.ts

# Seed tasks only (requires users and projects first)
docker-compose exec nextjs npx tsx scripts/seed-tasks.ts

# Seed test image data (requires tasks first)
docker-compose exec nextjs npx tsx scripts/seed-test-image.ts

# Seed real image from ~/Downloads/test-image.png (requires tasks first)
docker-compose exec nextjs npx tsx scripts/seed-real-image.ts

5. Access the Application

Open your browser and navigate to: http://localhost:3000

🧪 Test Data

The application includes comprehensive test data to get you started:

Users

• John Doe ([email protected])
• Jane Smith ([email protected])
• Bob Johnson ([email protected])
• Alice Williams ([email protected])
• Charlie Brown ([email protected])

Projects

1. Website Redesign (Leader: John Doe)
2. Mobile App Development (Leader: Jane Smith)
3. Database Migration (Leader: Bob Johnson)
4. API Integration (Leader: Alice Williams)
5. Security Audit (Leader: Charlie Brown)

Sample Tasks

Each project includes multiple tasks across different statuses:

Website Redesign Project:

• Design Homepage Mockup (Todo, High Priority, 8 points)
• Implement Responsive Layout (In Progress, High Priority, 13 points)
• Optimize Images and Assets (In Review, Medium Priority, 5 points)
• Write Documentation (Done, Low Priority, 3 points)

Mobile App Development Project:

• Set up React Native Project (Done, High Priority, 5 points)
• Design App Navigation (In Progress, High Priority, 8 points)
• Integrate API Endpoints (Todo, Medium Priority, 13 points)
• Test on iOS Simulator (Todo, Medium Priority, 5 points)

Database Migration Project:

• Backup Current Database (Done, Critical Priority, 3 points)
• Create Migration Scripts (In Progress, High Priority, 21 points)
• Test Migration Process (Todo, High Priority, 8 points)

API Integration Project:

• Research Third-party APIs (Done, Medium Priority, 5 points)
• Implement Payment Gateway (In Progress, High Priority, 13 points)
• Set up Email Service (Todo, Medium Priority, 8 points)

Security Audit Project:

• Vulnerability Assessment (In Progress, Critical Priority, 21 points)
• Update Security Policies (Todo, High Priority, 8 points)
• Implement Security Fixes (Todo, Critical Priority, 13 points)

All tasks include:

• Rich markdown descriptions
• Story points for estimation
• Priority levels (Low, Medium, High, Critical)
• Tags for categorization
• Assignees from the user pool

🔧 Local Development

Prerequisites

• Node.js 22+
• PostgreSQL (or use Docker)

Setup

1. Install Dependencies

   npm install

2. Environment Variables Create a .env.local file:

   DATABASE_URL=postgres://postgres:password@localhost:5432/kanban_db

3. Database Setup

   # Start PostgreSQL (if using Docker)
   docker-compose up postgres -d
   
   # Run migrations
   npm run db:migrate
   
   # Seed test data (option 1: complete reset)
   npx tsx scripts/reset-and-seed.ts
   
   # Or seed without clearing existing data (option 2)
   npx tsx scripts/seed-all.ts

4. Start Development Server

   npm run dev

📊 Database Schema

Tables

• USERS: Team members with first name, last name, and email
• PROJECTS: Projects with title, unique code (max 10 chars), markdown description, leader assignment, and task sequence tracking
• TASKS: Tasks with human-readable task_id, title, description, status, priority, assignee, position, and lifecycle timestamps
• TAGS: Task tags for categorization
• TASK_TAGS: Many-to-many relationship between tasks and tags
• IMAGE_METADATA: Image information including filename, content type, and task association
• IMAGE_DATA: Binary image data stored as base64 with optional thumbnails

Key Features

• Integer sequence primary keys
• Snake_case column naming (database) with camelCase mapping (JavaScript)
• Sparse numbering for efficient drag-and-drop operations
• Foreign key relationships with proper constraints

🎯 Usage

Creating Projects

1. Navigate to the home page
2. Click "Create New Project"
3. Enter project title and unique project code (ALL CAPS, max 10 characters)
4. Add an optional markdown description for detailed project specifications
5. Select a team leader
6. Click "Create Project"

Note: Project codes are immutable after creation and serve as unique identifiers for agent-based workflows.

Managing Tasks

1. Click on a project to open the Kanban board
2. Use the "Add Task" button to create new tasks
3. Drag and drop tasks between columns
4. Click on tasks to edit details, assignees, and descriptions

Image Attachments

1. Adding Images: Click the edit button on any task, then use "Add Images" in the Images section
2. Multiple Uploads: Select multiple images at once or add them in batches before saving
3. Viewing Images: Images are displayed as thumbnails in the task edit dialog
4. Deleting Images: Hover over any image and click the red X to mark for deletion
5. Staged Operations: All image uploads and deletions are staged until you click "Save Changes"

User Management

• Type-ahead search for users when assigning tasks or project leaders
• Users can be assigned to multiple tasks
• Project leaders can be changed via the edit dialog

🔄 Available Scripts

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server

# Database
npm run db:generate  # Generate new migrations
npm run db:migrate   # Run database migrations
npm run db:studio    # Open Drizzle Studio
npm run db:push      # Push schema changes

# Utilities
npm run lint         # Run ESLint

🌱 Seed Scripts

The project includes several specialized seed scripts for different use cases:

Complete Database Reset

# Clears ALL existing data and seeds fresh test data
npx tsx scripts/reset-and-seed.ts

Use when: Starting fresh or cleaning up corrupted data. This is the recommended approach for initial setup.

Comprehensive Seeding (Preserves Existing Data)

# Seeds all data types without clearing existing records
npx tsx scripts/seed-all.ts

Use when: Adding test data to an existing database without losing current records.

Individual Component Seeding

# Users (must be run first)
npx tsx scripts/seed-users.ts

# Projects (requires users)
npx tsx scripts/seed-projects.ts

# Tasks (requires users and projects)
npx tsx scripts/seed-tasks.ts

Use when: You need to seed specific data types or troubleshoot seeding issues.

Image Data Seeding

# Adds small test images (1x1 pixel PNG files)
npx tsx scripts/seed-test-image.ts

# Adds real image from ~/Downloads/test-image.png
npx tsx scripts/seed-real-image.ts

Prerequisites for image seeding:

• Tasks must exist in the database
• For seed-real-image.ts: Place a PNG file named test-image.png in your ~/Downloads folder

Use when: Testing image upload functionality or adding sample images to tasks.

Seeding Dependencies

The scripts have the following dependency chain:

1. Users → Must exist before projects
2. Projects → Must exist before tasks
3. Tasks → Must exist before images
4. Tags → Created automatically when seeding tasks

Note: reset-and-seed.ts and seed-all.ts handle all dependencies automatically.

🐳 Docker Commands

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild containers
docker-compose up --build

# Access PostgreSQL
docker-compose exec postgres psql -U postgres -d kanban_db

# Run commands in Next.js container
docker-compose exec nextjs npm run db:migrate

🏗️ Architecture

Frontend

• Next.js 15: App Router with server and client components
• React 19: Latest React features and hooks
• TypeScript: Full type safety
• shadcn/ui: Consistent, accessible UI components

Backend

• API Routes: Next.js API routes for data operations
• Drizzle ORM: Type-safe database operations
• PostgreSQL: Robust relational database

Key Patterns

• Optimistic Updates: UI updates immediately, syncs with server
• Sparse Numbering: Efficient drag-and-drop with minimal database writes
• Property Mapping: Consistent camelCase/snake_case conversion
• Error Handling: Graceful error recovery and user feedback

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📝 License

This project is licensed under the MIT License.

🆘 Troubleshooting

Common Issues

Database Connection Errors

• Ensure PostgreSQL is running: docker-compose ps
• Check environment variables are set correctly
• Verify database migrations have been run

Drag and Drop Not Working

• Check browser console for JavaScript errors
• Ensure you're not in edit mode (drag is disabled when editing)
• Verify the task card is not being blocked by other elements

User Search Not Working

• Ensure test data has been seeded: npx tsx scripts/seed-users.ts
• Check that users exist in the database
• Verify the search is case-insensitive

Performance Issues

• The sparse numbering algorithm should handle hundreds of tasks efficiently
• If experiencing slowdowns, check for infinite loops in React components
• Monitor database query performance

Getting Help

If you encounter issues:

1. Check the browser console for errors
2. Review the Docker logs: docker-compose logs -f
3. Verify all prerequisites are installed
4. Ensure database migrations and seeding completed successfully