PRD Example 21: Task Management API with Teams

Difficulty: Advanced | Project Type: REST API | Time: 2-3 weeks

---

Overview

What	A REST API for task management with team collaboration features
Who	Development teams building project management or productivity apps
Why	Provides a robust backend for multi-user task tracking with team workspaces

---

Core Features (MVP)

1. User Management: Register, login, profile management
2. Teams: Create teams, invite members, manage roles (admin/member)
3. Projects: Create projects within teams
4. Tasks: CRUD for tasks with status, assignee, due date
5. Task Comments: Add comments to tasks

---

Non-Goals

Will NOT build:

• File attachments
• Time tracking
• Kanban board logic (status only)
• Notifications or emails
• Activity feed or audit log
• Subtasks or dependencies
• Labels or tags
• Sprint or milestone tracking

Will NOT use:

• External email services
• Background job processors
• File storage services
• Complex permission libraries

---

Technical Constraints

Language	Python 3.11+
Framework	FastAPI
Database	PostgreSQL with SQLAlchemy
Auth	JWT with refresh tokens
Caching	Redis for rate limiting
Testing	pytest, httpx
Docs	OpenAPI (auto-generated)
Deploy	Docker + Railway

---

Success Criteria

• [ ] Users can register, login, refresh tokens
• [ ] Users can create and manage teams
• [ ] Team admins can invite members
• [ ] Projects belong to teams
• [ ] Tasks belong to projects with full CRUD
• [ ] Comments can be added to tasks
• [ ] Proper authorization (team members only)
• [ ] Rate limiting prevents abuse
• [ ] All tests pass

---

Implementation Phases

Phase 1: Project Setup & Auth

Goal: Set up project with JWT authentication

Tasks:

1. Create FastAPI project with proper structure
2. Set up PostgreSQL with SQLAlchemy models
3. Implement User model with password hashing
4. Create auth endpoints (register, login, refresh, logout)
5. Add JWT middleware for protected routes

Verification:

curl -X POST /auth/register \
  -d '{"email": "user@example.com", "password": "secret123", "name": "John"}'
# Returns: {"id": "...", "email": "...", "name": "John"}

curl -X POST /auth/login \
  -d '{"email": "user@example.com", "password": "secret123"}'
# Returns: {"access_token": "...", "refresh_token": "..."}

Deliverables: Auth system with JWT

---

Phase 2: Teams & Members

Goal: Implement team management

Tasks:

1. Create Team model (name, created_by)
2. Create TeamMember model (user_id, team_id, role)
3. Implement team CRUD endpoints
4. Implement member invitation (by email)
5. Implement role-based permissions (admin vs member)

Verification:

curl -X POST /teams -H "Authorization: Bearer ..." \
  -d '{"name": "Engineering"}'
# Returns: {"id": "...", "name": "Engineering", "role": "admin"}

curl -X POST /teams/{id}/members \
  -d '{"email": "colleague@example.com", "role": "member"}'
# Adds member to team

curl /teams/{id}/members
# Returns list of team members with roles

Deliverables: Team management API

---

Phase 3: Projects & Tasks

Goal: Implement projects and tasks

Tasks:

1. Create Project model (name, team_id, description)
2. Create Task model (title, description, status, assignee_id, due_date)
3. Implement project CRUD (team-scoped)
4. Implement task CRUD (project-scoped)
5. Add task status transitions (todo → in_progress → done)

Verification:

curl -X POST /teams/{team_id}/projects \
  -d '{"name": "Website Redesign"}'
# Creates project in team

curl -X POST /projects/{project_id}/tasks \
  -d '{"title": "Design homepage", "assignee_id": "...", "due_date": "2025-03-01"}'
# Creates task in project

curl -X PATCH /tasks/{task_id} \
  -d '{"status": "in_progress"}'
# Updates task status

Deliverables: Project and task management

---

Phase 4: Comments & Authorization

Goal: Add comments and secure endpoints

Tasks:

1. Create Comment model (task_id, user_id, content)
2. Implement comment CRUD
3. Add authorization middleware (team membership)
4. Verify task assignee is team member
5. Add rate limiting with Redis

Verification:

curl -X POST /tasks/{task_id}/comments \
  -d '{"content": "Looks good, ready for review"}'
# Adds comment

# Non-team member tries to access:
curl /teams/{team_id}/projects
# Returns: 403 Forbidden

# Rate limit test:
for i in {1..100}; do curl /tasks; done
# Returns: 429 Too Many Requests (after limit)

Deliverables: Comments and authorization

---

Phase 5: Testing & Deployment

Goal: Complete testing and deploy

Tasks:

1. Write comprehensive pytest test suite
2. Test auth flows, team permissions, task CRUD
3. Create Dockerfile and docker-compose.yml
4. Set up CI/CD with GitHub Actions
5. Deploy to Railway

Verification:

pytest --cov=app
# Coverage > 80%, all tests pass

docker-compose up
# App runs with PostgreSQL and Redis

# Deploy to Railway → API accessible
curl https://api.example.com/health
# Returns: {"status": "healthy"}

Deliverables: Deployed, tested API

---

Database Schema

class User(Base):
    id: UUID
    email: str (unique)
    password_hash: str
    name: str

class Team(Base):
    id: UUID
    name: str
    created_by: UUID (FK User)

class TeamMember(Base):
    user_id: UUID (FK User)
    team_id: UUID (FK Team)
    role: Enum("admin", "member")
    # Composite PK

class Project(Base):
    id: UUID
    team_id: UUID (FK Team)
    name: str
    description: str

class Task(Base):
    id: UUID
    project_id: UUID (FK Project)
    title: str
    description: str
    status: Enum("todo", "in_progress", "done")
    assignee_id: UUID (FK User, nullable)
    due_date: date (nullable)

class Comment(Base):
    id: UUID
    task_id: UUID (FK Task)
    user_id: UUID (FK User)
    content: str
    created_at: datetime

---

Agent Rules

Always	Ask First	Never
Check team membership before data access	Before changing database schema	Expose user passwords
Use UUIDs for public IDs	Before adding new endpoints	Allow cross-team data access
Validate assignee is team member	Before adding new features	Delete teams without confirmation
Apply rate limiting to all endpoints		Store plain text passwords