business-as-code/src/entities/projects.ts

Primitives for expressing business logic and processes as code

import type { Noun } from 'ai-database'

/**
 * Project Management Entities
 * Project, Task, Milestone, Sprint, Deliverable, Epic, Story, Resource
 */

export const Project: Noun = {
  singular: 'project',
  plural: 'projects',
  description: 'A project with defined scope, timeline, and deliverables',
  properties: {
    name: { type: 'string', description: 'Project name' },
    description: { type: 'string', description: 'Project description' },
    type: { type: 'string', description: 'Type of project', examples: ['product', 'internal', 'client', 'research', 'infrastructure', 'migration', 'integration', 'transformation'] },
    status: { type: 'string', description: 'Project status', examples: ['proposed', 'planning', 'approved', 'active', 'on-hold', 'completed', 'cancelled', 'archived'] },
    phase: { type: 'string', description: 'Current phase', examples: ['initiation', 'planning', 'execution', 'monitoring', 'closure'] },
    priority: { type: 'string', description: 'Project priority', examples: ['critical', 'high', 'medium', 'low'] },
    methodology: { type: 'string', description: 'Project methodology', examples: ['agile', 'scrum', 'kanban', 'waterfall', 'hybrid', 'lean'] },
    code: { type: 'string', description: 'Project code or identifier' },
    objectives: { type: 'string[]', description: 'Project objectives' },
    scope: { type: 'string', description: 'Project scope' },
    outOfScope: { type: 'string[]', description: 'Out of scope items' },
    assumptions: { type: 'string[]', description: 'Project assumptions' },
    constraints: { type: 'string[]', description: 'Project constraints' },
    dependencies: { type: 'string[]', description: 'External dependencies' },
    startDate: { type: 'date', description: 'Planned start date' },
    endDate: { type: 'date', description: 'Planned end date' },
    actualStartDate: { type: 'date', description: 'Actual start date', optional: true },
    actualEndDate: { type: 'date', description: 'Actual end date', optional: true },
    deadline: { type: 'date', description: 'Hard deadline', optional: true },
    progress: { type: 'number', description: 'Progress percentage' },
    health: { type: 'string', description: 'Project health', examples: ['on-track', 'at-risk', 'off-track', 'blocked'] },
    budget: { type: 'number', description: 'Total budget' },
    spent: { type: 'number', description: 'Amount spent' },
    remaining: { type: 'number', description: 'Budget remaining' },
    forecast: { type: 'number', description: 'Forecasted total cost' },
    variance: { type: 'number', description: 'Budget variance' },
    currency: { type: 'string', description: 'Budget currency' },
    sponsor: { type: 'string', description: 'Executive sponsor' },
    owner: { type: 'string', description: 'Project owner' },
    manager: { type: 'string', description: 'Project manager' },
    teamLead: { type: 'string', description: 'Technical lead' },
    teamSize: { type: 'number', description: 'Team size' },
    stakeholders: { type: 'string[]', description: 'Key stakeholders' },
    businessUnit: { type: 'string', description: 'Business unit' },
    portfolio: { type: 'string', description: 'Portfolio or program' },
    category: { type: 'string', description: 'Project category' },
    tags: { type: 'string[]', description: 'Project tags' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    tasks: { type: 'task[]', description: 'Project tasks', backref: 'project' },
    milestones: { type: 'milestone[]', description: 'Project milestones', backref: 'project' },
    deliverables: { type: 'deliverable[]', description: 'Project deliverables', backref: 'project' },
    sprints: { type: 'sprint[]', description: 'Project sprints', backref: 'project' },
    epics: { type: 'epic[]', description: 'Project epics', backref: 'project' },
    resources: { type: 'resource[]', description: 'Assigned resources', backref: 'projects' },
    risks: { type: 'risk[]', description: 'Project risks', backref: 'project' },
    team: { type: 'team', description: 'Project team', backref: 'projects' },
    parentProject: { type: 'project', description: 'Parent project', backref: 'subProjects' },
    subProjects: { type: 'project[]', description: 'Sub-projects', backref: 'parentProject' },
  },
  actions: ['create', 'update', 'plan', 'approve', 'start', 'pause', 'resume', 'complete', 'cancel', 'archive', 'replan', 'review'],
  events: ['created', 'updated', 'planned', 'approved', 'started', 'paused', 'resumed', 'completed', 'cancelled', 'archived', 'replanned', 'reviewed'],
}

export const Task: Noun = {
  singular: 'task',
  plural: 'tasks',
  description: 'A task or work item to be completed',
  properties: {
    name: { type: 'string', description: 'Task name' },
    description: { type: 'string', description: 'Task description' },
    type: { type: 'string', description: 'Type of task', examples: ['task', 'bug', 'feature', 'improvement', 'research', 'documentation', 'test', 'review', 'deployment'] },
    status: { type: 'string', description: 'Task status', examples: ['backlog', 'todo', 'in-progress', 'review', 'blocked', 'done', 'cancelled'] },
    priority: { type: 'string', description: 'Task priority', examples: ['critical', 'high', 'medium', 'low'] },
    resolution: { type: 'string', description: 'Resolution status', examples: ['unresolved', 'fixed', 'wont-fix', 'duplicate', 'cannot-reproduce', 'deferred'] },
    estimate: { type: 'number', description: 'Estimated hours/points' },
    timeSpent: { type: 'number', description: 'Time spent' },
    remaining: { type: 'number', description: 'Time remaining' },
    storyPoints: { type: 'number', description: 'Story points' },
    complexity: { type: 'string', description: 'Complexity level', examples: ['trivial', 'simple', 'medium', 'complex', 'unknown'] },
    startDate: { type: 'date', description: 'Start date' },
    dueDate: { type: 'date', description: 'Due date' },
    completedDate: { type: 'date', description: 'Completion date', optional: true },
    assignee: { type: 'string', description: 'Assigned person' },
    reporter: { type: 'string', description: 'Task reporter' },
    reviewer: { type: 'string', description: 'Task reviewer' },
    labels: { type: 'string[]', description: 'Task labels' },
    components: { type: 'string[]', description: 'Affected components' },
    acceptanceCriteria: { type: 'string[]', description: 'Acceptance criteria' },
    blockedReason: { type: 'string', description: 'Blocked reason', optional: true },
    pullRequest: { type: 'string', description: 'PR/MR link', optional: true },
    branch: { type: 'string', description: 'Git branch', optional: true },
    progress: { type: 'number', description: 'Progress percentage' },
    externalId: { type: 'string', description: 'External system ID', optional: true },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Task tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    project: { type: 'project', description: 'Parent project', backref: 'tasks' },
    epic: { type: 'epic', description: 'Parent epic', backref: 'tasks' },
    story: { type: 'story', description: 'Parent story', backref: 'tasks' },
    sprint: { type: 'sprint', description: 'Assigned sprint', backref: 'tasks' },
    milestone: { type: 'milestone', description: 'Target milestone', backref: 'tasks' },
    parentTask: { type: 'task', description: 'Parent task', backref: 'subtasks' },
    subtasks: { type: 'task[]', description: 'Subtasks', backref: 'parentTask' },
    blockedBy: { type: 'task[]', description: 'Blocked by tasks', backref: 'blocks' },
    blocks: { type: 'task[]', description: 'Tasks this blocks', backref: 'blockedBy' },
    relatedTasks: { type: 'task[]', description: 'Related tasks', backref: 'relatedTasks' },
  },
  actions: ['create', 'update', 'assign', 'start', 'pause', 'resume', 'complete', 'cancel', 'reopen', 'block', 'unblock', 'estimate', 'review'],
  events: ['created', 'updated', 'assigned', 'started', 'paused', 'resumed', 'completed', 'cancelled', 'reopened', 'blocked', 'unblocked', 'estimated', 'reviewed'],
}

export const Milestone: Noun = {
  singular: 'milestone',
  plural: 'milestones',
  description: 'A project milestone or checkpoint',
  properties: {
    name: { type: 'string', description: 'Milestone name' },
    description: { type: 'string', description: 'Milestone description' },
    type: { type: 'string', description: 'Type of milestone', examples: ['phase-gate', 'release', 'delivery', 'review', 'approval', 'launch', 'go-live'] },
    status: { type: 'string', description: 'Milestone status', examples: ['planned', 'in-progress', 'completed', 'delayed', 'at-risk', 'cancelled'] },
    targetDate: { type: 'date', description: 'Target date' },
    actualDate: { type: 'date', description: 'Actual completion date', optional: true },
    progress: { type: 'number', description: 'Progress percentage' },
    deliverables: { type: 'string[]', description: 'Expected deliverables' },
    criteria: { type: 'string[]', description: 'Completion criteria' },
    owner: { type: 'string', description: 'Milestone owner' },
    approver: { type: 'string', description: 'Milestone approver' },
    approved: { type: 'boolean', description: 'Has been approved' },
    approvalDate: { type: 'date', description: 'Approval date', optional: true },
    blockers: { type: 'string[]', description: 'Current blockers' },
    dependencies: { type: 'string[]', description: 'Dependencies' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Milestone tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    project: { type: 'project', description: 'Parent project', backref: 'milestones', required: true },
    tasks: { type: 'task[]', description: 'Milestone tasks', backref: 'milestone' },
    deliverables: { type: 'deliverable[]', description: 'Milestone deliverables', backref: 'milestone' },
    previousMilestone: { type: 'milestone', description: 'Previous milestone', backref: 'nextMilestone' },
    nextMilestone: { type: 'milestone', description: 'Next milestone', backref: 'previousMilestone' },
  },
  actions: ['create', 'update', 'start', 'complete', 'delay', 'approve', 'cancel', 'review'],
  events: ['created', 'updated', 'started', 'completed', 'delayed', 'approved', 'cancelled', 'reviewed'],
}

export const Sprint: Noun = {
  singular: 'sprint',
  plural: 'sprints',
  description: 'A time-boxed iteration in agile development',
  properties: {
    name: { type: 'string', description: 'Sprint name' },
    number: { type: 'number', description: 'Sprint number' },
    goal: { type: 'string', description: 'Sprint goal' },
    status: { type: 'string', description: 'Sprint status', examples: ['planning', 'active', 'review', 'completed', 'cancelled'] },
    startDate: { type: 'date', description: 'Sprint start date' },
    endDate: { type: 'date', description: 'Sprint end date' },
    duration: { type: 'number', description: 'Duration in days' },
    capacity: { type: 'number', description: 'Team capacity (points/hours)' },
    commitment: { type: 'number', description: 'Committed points/hours' },
    completed: { type: 'number', description: 'Completed points/hours' },
    velocity: { type: 'number', description: 'Sprint velocity' },
    completionRate: { type: 'number', description: 'Completion rate percentage' },
    carryOver: { type: 'number', description: 'Points carried over' },
    addedScope: { type: 'number', description: 'Scope added during sprint' },
    removedScope: { type: 'number', description: 'Scope removed during sprint' },
    totalTasks: { type: 'number', description: 'Total tasks' },
    completedTasks: { type: 'number', description: 'Completed tasks' },
    inProgressTasks: { type: 'number', description: 'In-progress tasks' },
    blockedTasks: { type: 'number', description: 'Blocked tasks' },
    retroNotes: { type: 'string', description: 'Retrospective notes', optional: true },
    retroUrl: { type: 'string', description: 'Retrospective document URL', optional: true },
    reviewUrl: { type: 'string', description: 'Sprint review document URL', optional: true },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Sprint tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    project: { type: 'project', description: 'Parent project', backref: 'sprints', required: true },
    tasks: { type: 'task[]', description: 'Sprint tasks', backref: 'sprint' },
    stories: { type: 'story[]', description: 'Sprint stories', backref: 'sprint' },
    team: { type: 'team', description: 'Sprint team', backref: 'sprints' },
    previousSprint: { type: 'sprint', description: 'Previous sprint', backref: 'nextSprint' },
    nextSprint: { type: 'sprint', description: 'Next sprint', backref: 'previousSprint' },
  },
  actions: ['create', 'update', 'plan', 'start', 'complete', 'cancel', 'review', 'retrospect'],
  events: ['created', 'updated', 'planned', 'started', 'completed', 'cancelled', 'reviewed', 'retrospected'],
}

export const Deliverable: Noun = {
  singular: 'deliverable',
  plural: 'deliverables',
  description: 'A project deliverable or output',
  properties: {
    name: { type: 'string', description: 'Deliverable name' },
    description: { type: 'string', description: 'Deliverable description' },
    type: { type: 'string', description: 'Type of deliverable', examples: ['document', 'software', 'report', 'design', 'prototype', 'training', 'process', 'artifact'] },
    status: { type: 'string', description: 'Deliverable status', examples: ['planned', 'in-progress', 'review', 'approved', 'delivered', 'rejected'] },
    format: { type: 'string', description: 'Deliverable format' },
    version: { type: 'string', description: 'Current version' },
    dueDate: { type: 'date', description: 'Due date' },
    deliveredDate: { type: 'date', description: 'Delivery date', optional: true },
    owner: { type: 'string', description: 'Deliverable owner' },
    reviewer: { type: 'string', description: 'Deliverable reviewer' },
    acceptor: { type: 'string', description: 'Acceptance authority' },
    acceptanceCriteria: { type: 'string[]', description: 'Acceptance criteria' },
    accepted: { type: 'boolean', description: 'Has been accepted' },
    acceptanceDate: { type: 'date', description: 'Acceptance date', optional: true },
    comments: { type: 'string', description: 'Review comments', optional: true },
    url: { type: 'string', description: 'Deliverable URL' },
    progress: { type: 'number', description: 'Progress percentage' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Deliverable tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    project: { type: 'project', description: 'Parent project', backref: 'deliverables', required: true },
    milestone: { type: 'milestone', description: 'Target milestone', backref: 'deliverables' },
    tasks: { type: 'task[]', description: 'Related tasks', backref: 'deliverable' },
    dependencies: { type: 'deliverable[]', description: 'Dependent deliverables', backref: 'dependents' },
    dependents: { type: 'deliverable[]', description: 'Deliverables that depend on this', backref: 'dependencies' },
  },
  actions: ['create', 'update', 'start', 'submit', 'review', 'approve', 'reject', 'revise', 'deliver', 'accept'],
  events: ['created', 'updated', 'started', 'submitted', 'reviewed', 'approved', 'rejected', 'revised', 'delivered', 'accepted'],
}

export const Epic: Noun = {
  singular: 'epic',
  plural: 'epics',
  description: 'A large body of work that can be broken into stories',
  properties: {
    name: { type: 'string', description: 'Epic name' },
    description: { type: 'string', description: 'Epic description' },
    status: { type: 'string', description: 'Epic status', examples: ['draft', 'ready', 'in-progress', 'done', 'cancelled'] },
    priority: { type: 'string', description: 'Epic priority', examples: ['critical', 'high', 'medium', 'low'] },
    theme: { type: 'string', description: 'Epic theme or initiative' },
    businessValue: { type: 'string', description: 'Business value statement' },
    hypothesis: { type: 'string', description: 'Business hypothesis', optional: true },
    successMetrics: { type: 'string[]', description: 'Success metrics' },
    acceptanceCriteria: { type: 'string[]', description: 'Acceptance criteria' },
    startDate: { type: 'date', description: 'Start date' },
    targetDate: { type: 'date', description: 'Target completion date' },
    completedDate: { type: 'date', description: 'Completion date', optional: true },
    estimate: { type: 'number', description: 'Estimated points' },
    completed: { type: 'number', description: 'Completed points' },
    progress: { type: 'number', description: 'Progress percentage' },
    owner: { type: 'string', description: 'Epic owner' },
    labels: { type: 'string[]', description: 'Epic labels' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Epic tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    project: { type: 'project', description: 'Parent project', backref: 'epics', required: true },
    stories: { type: 'story[]', description: 'Epic stories', backref: 'epic' },
    tasks: { type: 'task[]', description: 'Epic tasks', backref: 'epic' },
    initiative: { type: 'initiative', description: 'Parent initiative', backref: 'epics' },
    dependencies: { type: 'epic[]', description: 'Dependent epics', backref: 'dependents' },
  },
  actions: ['create', 'update', 'refine', 'start', 'complete', 'cancel', 'split', 'prioritize'],
  events: ['created', 'updated', 'refined', 'started', 'completed', 'cancelled', 'split', 'prioritized'],
}

export const Story: Noun = {
  singular: 'story',
  plural: 'stories',
  description: 'A user story representing a feature from user perspective',
  properties: {
    name: { type: 'string', description: 'Story name' },
    description: { type: 'string', description: 'Story description' },
    userStory: { type: 'string', description: 'As a... I want... So that...' },
    status: { type: 'string', description: 'Story status', examples: ['draft', 'ready', 'in-progress', 'review', 'done', 'cancelled'] },
    priority: { type: 'string', description: 'Story priority', examples: ['critical', 'high', 'medium', 'low'] },
    storyPoints: { type: 'number', description: 'Story points estimate' },
    businessValue: { type: 'number', description: 'Business value score' },
    acceptanceCriteria: { type: 'string[]', description: 'Acceptance criteria' },
    definition: { type: 'string', description: 'Definition of done criteria' },
    persona: { type: 'string', description: 'Target user persona' },
    assignee: { type: 'string', description: 'Assigned person' },
    reporter: { type: 'string', description: 'Story reporter' },
    labels: { type: 'string[]', description: 'Story labels' },
    components: { type: 'string[]', description: 'Affected components' },
    startDate: { type: 'date', description: 'Start date' },
    dueDate: { type: 'date', description: 'Due date' },
    completedDate: { type: 'date', description: 'Completion date', optional: true },
    progress: { type: 'number', description: 'Progress percentage' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Story tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    epic: { type: 'epic', description: 'Parent epic', backref: 'stories' },
    project: { type: 'project', description: 'Parent project', backref: 'stories' },
    sprint: { type: 'sprint', description: 'Assigned sprint', backref: 'stories' },
    tasks: { type: 'task[]', description: 'Story tasks', backref: 'story' },
    blockedBy: { type: 'story[]', description: 'Blocked by stories', backref: 'blocks' },
    blocks: { type: 'story[]', description: 'Stories this blocks', backref: 'blockedBy' },
  },
  actions: ['create', 'update', 'refine', 'estimate', 'assign', 'start', 'complete', 'reject', 'split'],
  events: ['created', 'updated', 'refined', 'estimated', 'assigned', 'started', 'completed', 'rejected', 'split'],
}

export const Resource: Noun = {
  singular: 'resource',
  plural: 'resources',
  description: 'A project resource (person, equipment, or material)',
  properties: {
    name: { type: 'string', description: 'Resource name' },
    type: { type: 'string', description: 'Type of resource', examples: ['person', 'equipment', 'material', 'facility', 'budget', 'software'] },
    status: { type: 'string', description: 'Resource status', examples: ['available', 'assigned', 'unavailable', 'on-leave', 'overallocated'] },
    role: { type: 'string', description: 'Resource role or function' },
    skills: { type: 'string[]', description: 'Skills or capabilities' },
    capacity: { type: 'number', description: 'Total capacity (hours/units)' },
    allocated: { type: 'number', description: 'Currently allocated' },
    available: { type: 'number', description: 'Available capacity' },
    utilizationTarget: { type: 'number', description: 'Target utilization percentage' },
    utilizationActual: { type: 'number', description: 'Actual utilization percentage' },
    costRate: { type: 'number', description: 'Cost rate per hour/unit' },
    billableRate: { type: 'number', description: 'Billable rate per hour/unit', optional: true },
    currency: { type: 'string', description: 'Rate currency' },
    location: { type: 'string', description: 'Resource location' },
    timezone: { type: 'string', description: 'Time zone' },
    startDate: { type: 'date', description: 'Availability start' },
    endDate: { type: 'date', description: 'Availability end', optional: true },
    manager: { type: 'string', description: 'Resource manager' },
    email: { type: 'string', description: 'Contact email', optional: true },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Resource tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    projects: { type: 'project[]', description: 'Assigned projects', backref: 'resources' },
    tasks: { type: 'task[]', description: 'Assigned tasks', backref: 'resource' },
    team: { type: 'team', description: 'Resource team', backref: 'resources' },
    worker: { type: 'worker', description: 'Worker profile', backref: 'resource' },
  },
  actions: ['create', 'update', 'allocate', 'deallocate', 'reassign', 'book', 'release'],
  events: ['created', 'updated', 'allocated', 'deallocated', 'reassigned', 'booked', 'released'],
}

// Export all project entities
export const ProjectEntities = {
  Project,
  Task,
  Milestone,
  Sprint,
  Deliverable,
  Epic,
  Story,
  Resource,
}

export default ProjectEntities