Building Block #16: Goals / OKR Tracking

Status: 📋 Planned Dependencies: Building Block #11 (Employee Management), Building Block #07 (AI Service) When: Month 5-6 (ADD-ON Phase) Context: Solo Developer + AI

Definition

Implement basic goal tracking with OKR support:

• Create goals (personal, team, company)
• Progress tracking (0-100%)
• Optional key results
• AI goal suggestions based on role
• Manager review of team goals
• Goal status workflow

Dependencies

• ✅ Building Block #11: Employee Management
  • Employee model exists
  • Manager relationships established
  • Tag system available for goal tagging
  • Custom fields available for goal metadata
• ✅ Building Block #07: AI Service Setup
  • AI service available for goal suggestions
• Requires existing foundation patterns

Implementation Checklist

GATE 1: BUILD

Database Models

• Create Goal model
  • id (UUID)
  • tenantId
  • ownerId (employeeId - goal owner)
  • ownerType (PERSONAL, TEAM, DEPARTMENT, COMPANY)
  • teamId (optional, for TEAM goals)
  • departmentId (optional, for DEPARTMENT goals)
  • title
  • description
  • category (optional - performance, development, project, etc.)
  • progress (0-100 integer)
  • status (DRAFT, ACTIVE, COMPLETED, CANCELLED, ON_HOLD)
  • startDate
  • dueDate
  • completedAt (optional)
  • parentGoalId (optional, for goal alignment)
  • createdAt, updatedAt
• Create KeyResult model
  • id (UUID)
  • goalId
  • title
  • description
  • targetValue (numeric target)
  • currentValue (current progress)
  • unit (optional - %, count, currency, etc.)
  • progress (0-100, calculated from target/current)
  • status (NOT_STARTED, IN_PROGRESS, COMPLETED, AT_RISK)
  • createdAt, updatedAt
• Create GoalComment model
  • id (UUID)
  • goalId
  • authorId (employeeId)
  • content
  • createdAt, updatedAt
• Create GoalCheckIn model (progress updates)
  • id (UUID)
  • goalId
  • authorId (employeeId)
  • previousProgress
  • newProgress
  • notes
  • createdAt
• Create GoalTag junction table (reuse Tag system from #11)
  • goalId, tagId (composite PK)
  • assignedAt, assignedBy
• Add relationships
  • Goal ↔ Employee (owner, many-to-one)
  • Goal ↔ Team (optional, many-to-one)
  • Goal ↔ Department (optional, many-to-one)
  • Goal ↔ Goal (parent alignment, self-reference)
  • KeyResult ↔ Goal (many-to-one)
  • GoalComment ↔ Goal, Employee
  • GoalCheckIn ↔ Goal, Employee
• Create migration
• Add indexes
  • Goal(tenantId, ownerId)
  • Goal(tenantId, ownerType, status)
  • Goal(tenantId, dueDate)
  • KeyResult(goalId)
  • GoalCheckIn(goalId, createdAt)

Backend Implementation

• Create GoalModule
• Create GoalRepository (with tenant filtering)
• Create GoalController
  • GET /api/v1/goals (list with filters: owner, status, type)
  • GET /api/v1/goals/:id (get single goal with key results)
  • POST /api/v1/goals (create goal)
  • PUT /api/v1/goals/:id (update goal)
  • DELETE /api/v1/goals/:id (delete goal)
  • PUT /api/v1/goals/:id/progress (update progress)
  • PUT /api/v1/goals/:id/status (update status)
  • GET /api/v1/goals/:id/check-ins (get check-in history)
  • POST /api/v1/goals/:id/check-ins (add check-in)
  • POST /api/v1/goals/:id/comments (add comment)
• Create KeyResultController
  • GET /api/v1/goals/:goalId/key-results (list)
  • POST /api/v1/goals/:goalId/key-results (create)
  • PUT /api/v1/goals/:goalId/key-results/:id (update)
  • DELETE /api/v1/goals/:goalId/key-results/:id (delete)
• Create GoalService with:
  • Goal progress calculation (average of key results if present)
  • Permission checking (owner, manager, admin)
  • Status transitions validation
  • Goal alignment logic
• Create GoalSuggestionService
  • POST /api/v1/goals/suggestions (AI-generated suggestions)
  • Input: job title, department, existing goals
  • Call AI service for suggestions
• Add DTOs with validation
  • CreateGoalDto (title, description, ownerType, dates)
  • UpdateProgressDto (progress, notes)
  • CreateKeyResultDto (title, targetValue, unit)
  • GoalResponseDto (with key results, progress)
• Add permission checks
  • goals:read (view own + team goals)
  • goals:create (create own goals)
  • goals:manage (manager - review team goals)
  • goals:admin (admin - manage all goals)

AI Integration

• Implement AI goal suggestions
  • Call AI service with context (role, department, company goals)
  • Return 3-5 suggested goals with key results
  • Based on job title and industry best practices
• Optional: AI progress insights
  • Analyze check-in patterns
  • Suggest adjustments to at-risk goals

Frontend Implementation

• Create goals list page (with filters)
• Create goal detail page
• Create goal creation/edit form
• Create key results management UI
• Create progress bar component
• Create check-in modal
• Create AI suggestions component
• Create goal alignment view (show parent/child goals)
• Create manager review dashboard
• Create goal status badges
• Add loading states and error handling

GATE 2: TEST

• Test goal CRUD operations
• Test key result CRUD operations
• Test progress calculation (with/without key results)
• Test status transitions
• Test check-in recording
• Test goal alignment (parent-child)
• Test AI suggestions endpoint
• Test permission enforcement (owner, manager, admin)
• Test tenant isolation
• Write unit tests
• Write integration tests
• All tests passing

GATE 3: REVIEW & APPROVE

• Self-review implementation
• Verify progress calculation accuracy
• Check AI suggestions quality
• Verify permission model works correctly
• Test manager review workflow
• Document approval reasoning
• Status: ✅ APPROVED

GATE 4: DOCUMENT

• Document goals architecture
• Document OKR model (goals + key results)
• Document progress calculation logic
• Document AI suggestions integration
• Document permission model
• Update API documentation
• Update .cursorrules
• Update CLAUDE.md
• Update memory log

GATE 5: COMMIT & TAG

• Git commit with clear message: "Building Block #16: Goals / OKR Tracking complete"
• Tag: building-block-16-goals-okr
• Push to main
• Update status tracker

Testing Requirements

Unit Tests

• Progress calculation (goal + key results)
• Status transition validation
• Permission checking logic
• AI suggestion parsing

Integration Tests

• Goal creation flow
• Key result CRUD
• Check-in recording
• AI suggestions endpoint
• Manager review workflow
• Tenant isolation

Documentation Requirements

• Goals/OKR architecture
• Progress calculation documentation
• AI suggestions integration
• Permission model guide
• API endpoint documentation
• Frontend component guide

Approval Criteria

Building block is complete when:

• ✅ Goal CRUD working
• ✅ Key results working
• ✅ Progress tracking working (manual + calculated)
• ✅ Check-ins working
• ✅ Status workflow working
• ✅ AI suggestions working
• ✅ Manager review working
• ✅ Goal alignment (parent/child) working
• ✅ All tests passing
• ✅ Documentation complete

AI Context

What AI needs to know:

• Goals have ownerType: PERSONAL, TEAM, DEPARTMENT, COMPANY
• Progress: 0-100 integer, calculated from key results if present
• Key results have targetValue/currentValue → progress percentage
• Goal progress = average of key result progress (if KRs exist)
• Status flow: DRAFT → ACTIVE → COMPLETED/CANCELLED/ON_HOLD
• AI suggestions based on job title and department
• Reuse Tag system from Building Block #11 for goal categorization
• Reuse Custom Fields from Building Block #11 for goal metadata

Patterns to follow:

• Repository methods filter by tenantId
• Use @RequirePermissions() decorator
• Permission levels: own goals, team goals (manager), all goals (admin)
• Progress auto-calculated from key results when present
• Check-ins create history for progress changes
• AI suggestions via AI Service (Building Block #07)

Simplified Design Choices

Based on feature-phases.mdx guidance:

• ✅ Basic goal CRUD
• ✅ Simple progress bar (0-100%)
• ✅ AI suggestions (based on job title only)
• ✅ Basic goal alignment (single parent)
• ❌ No complex cascading goals
• ❌ No performance review integration (future)
• ❌ No automated reminders (future)

Next Building Block

After completion, proceed to Building Block #17: Advanced RBAC Permissions

---

Last Updated: 2025-11-27