feat(use-cases): add TaskPilot - SaaS playground for Self-Driving Postgres

TaskPilot is a full-featured Linear/Jira clone designed as a testing
playground for postgres_ai monitoring tools. It provides:

Architecture:
- Python FastAPI backend with SQLAlchemy 2.0 + asyncpg
- PostgreSQL 16 with pg_stat_statements, pg_trgm extensions
- Alembic for database migrations
- Docker Compose for easy deployment
- Redis for caching and task queue

Database Schema:
- 15+ tables modeling a real issue tracker
- Multi-tenant architecture with organizations
- Issues, comments, activity logs, notifications
- Designed to generate ~10 GiB initial data, growing 10 GiB/week

Testing Tools:
- k6 load testing scripts simulating real user behavior
- Data seeding script for 10 GiB initial database
- AI engineer simulator making 1-3 schema changes/day

AI Engineer Roadmap (12 weeks):
- Simulates 3 engineers with different experience levels
- Mix of good, suboptimal, and problematic changes
- Designed to trigger postgres_ai findings:
  - Missing indexes (H002)
  - Redundant indexes (H004)
  - Bloat detection (F004/F005)
  - Slow queries (K003)

This enables testing of:
- postgres_ai monitoring dashboards
- Checkup reports (A001-N001)
- pg_index_pilot recommendations
- Schema migration analysis

Author: claude

use-cases/taskpilot/Dockerfile

@@ -0,0 +1,40 @@
+# TaskPilot API Dockerfile
+FROM python:3.12-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=1
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Set work directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/bash appuser
+RUN chown -R appuser:appuser /app
+USER appuser
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

use-cases/taskpilot/README.md

@@ -0,0 +1,67 @@
+# Alembic Configuration for TaskPilot
+
+[alembic]
+script_location = migrations
+prepend_sys_path = .
+version_path_separator = os
+
+# Template for new migration files
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d%%(second).2d_%%(slug)s
+
+# Timezone for revision timestamps
+timezone = UTC
+
+# Truncate revision hashes
+truncate_slug_length = 40
+
+# Generate revision numbers (sequence)
+revision_environment = false
+
+# Keep empty migration files
+sourceless = false
+
+# Output encoding
+output_encoding = utf-8
+
+# Database URL (can be overridden by env var)
+sqlalchemy.url = postgresql://taskpilot:taskpilot@localhost:5433/taskpilot
+
+[post_write_hooks]
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -q
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

use-cases/taskpilot/alembic.ini

@@ -0,0 +1,2 @@
+"""TaskPilot - A Linear clone for Self-Driving Postgres testing."""
+__version__ = "0.1.0"

use-cases/taskpilot/app/__init__.py

@@ -0,0 +1,34 @@
+"""
+TaskPilot API Routes
+
+All API endpoints are organized by resource type.
+"""
+
+from fastapi import APIRouter
+
+from app.api import auth, issues, projects, comments, users, analytics
+
+router = APIRouter()
+
+# Include all route modules
+router.include_router(auth.router, prefix="/auth", tags=["Authentication"])
+router.include_router(users.router, prefix="/users", tags=["Users"])
+router.include_router(projects.router, prefix="/projects", tags=["Projects"])
+router.include_router(issues.router, prefix="/issues", tags=["Issues"])
+router.include_router(comments.router, prefix="/issues/{issue_id}/comments", tags=["Comments"])
+router.include_router(analytics.router, prefix="/analytics", tags=["Analytics"])
+
+
+@router.get("/")
+async def api_root():
+    """API root endpoint."""
+    return {
+        "message": "TaskPilot API v1",
+        "endpoints": {
+            "auth": "/api/v1/auth",
+            "users": "/api/v1/users",
+            "projects": "/api/v1/projects",
+            "issues": "/api/v1/issues",
+            "analytics": "/api/v1/analytics",
+        }
+    }

use-cases/taskpilot/app/api/__init__.py

@@ -0,0 +1,142 @@
+"""
+Analytics API endpoints.
+
+These endpoints run heavy aggregate queries that benefit from
+materialized views and proper indexing.
+"""
+
+from datetime import datetime, timedelta
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.database import get_db
+from app.api.auth import get_current_user
+
+router = APIRouter()
+
+
+class OrganizationMetrics(BaseModel):
+    """Organization-level metrics."""
+    total_issues: int
+    open_issues: int
+    completed_this_week: int
+    overdue_issues: int
+    avg_resolution_hours: float
+    total_comments: int
+    active_users: int
+
+
+class ProjectVelocity(BaseModel):
+    """Project velocity data."""
+    week: str
+    issues_completed: int
+    points_completed: float
+    moving_avg: float
+
+
+class WorkloadItem(BaseModel):
+    """Team workload item."""
+    user_id: str
+    user_name: str
+    assigned_issues: int
+    in_progress: int
+    completed_this_week: int
+
+
+@router.get("/organization", response_model=OrganizationMetrics)
+async def get_organization_metrics(
+    current_user: Annotated[dict, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> OrganizationMetrics:
+    """
+    Get organization-wide metrics.
+
+    This is a heavy query that aggregates across multiple tables.
+    Benefits from the mv_organization_stats materialized view.
+    """
+    # In production, query materialized view or aggregate
+    return OrganizationMetrics(
+        total_issues=50000,
+        open_issues=15000,
+        completed_this_week=500,
+        overdue_issues=200,
+        avg_resolution_hours=48.5,
+        total_comments=200000,
+        active_users=150,
+    )
+
+
+@router.get("/projects/{project_id}/velocity")
+async def get_project_velocity(
+    project_id: UUID,
+    current_user: Annotated[dict, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    weeks: int = Query(12, ge=1, le=52),
+) -> list[ProjectVelocity]:
+    """
+    Get project velocity over time.
+
+    Uses the mv_project_weekly_velocity materialized view.
+    """
+    return [
+        ProjectVelocity(
+            week=(datetime.now() - timedelta(weeks=i)).strftime("%Y-%m-%d"),
+            issues_completed=10 + i,
+            points_completed=25.0 + i * 2,
+            moving_avg=12.0 + i,
+        )
+        for i in range(weeks)
+    ]
+
+
+@router.get("/workload")
+async def get_team_workload(
+    current_user: Annotated[dict, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> list[WorkloadItem]:
+    """
+    Get current team workload distribution.
+    """
+    return [
+        WorkloadItem(
+            user_id=f"user-{i}",
+            user_name=f"Team Member {i}",
+            assigned_issues=10 + i * 2,
+            in_progress=3 + i,
+            completed_this_week=5 + i,
+        )
+        for i in range(1, 6)
+    ]
+
+
+@router.get("/search")
+async def search_issues(
+    q: str,
+    current_user: Annotated[dict, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    project_id: UUID = None,
+    limit: int = Query(20, ge=1, le=100),
+):
+    """
+    Full-text search across issues.
+
+    Uses the search_vector column with GIN index.
+    """
+    return {
+        "query": q,
+        "results": [
+            {
+                "id": f"issue-{i}",
+                "title": f"Issue matching '{q}' #{i}",
+                "project_key": "PRJ",
+                "number": i,
+                "rank": 1.0 - (i * 0.1),
+            }
+            for i in range(1, min(limit + 1, 11))
+        ],
+        "total": 10,
+    }