Project Management

Project Management Use Cases

This document describes real-world scenarios for project management in Global Watch, including creating, updating, archiving, and deleting projects.

UC-001: Create Project

Description

User creates a new forest monitoring project within their account (personal or team). The system validates permissions, creates the project record, initializes default settings, and tracks usage.

Actors

• Primary: Authenticated User
• Secondary: Billing System, Usage Tracking System

Preconditions

• User is authenticated
• User has permission to create projects in the account
• Account has not exceeded project quota

Postconditions

• Project created with unique ID and slug
• Project ownership assigned to account
• Default settings initialized
• Usage tracking started
• Audit log entry created

Main Flow

1. User navigates to Projects page
2. User clicks "Create Project" button
3. User enters project details:
   • Name: "Al Maha Forest Monitoring 2025"
   • Slug: Auto-generated as al-maha-forest-monitoring-2025
   • Description: Optional project description
4. System validates slug uniqueness within account
5. System checks account project quota
6. System creates project record
7. System initializes default settings
8. System starts usage tracking
9. User is redirected to new project dashboard

Alternative Flows

A1: Slug Already Exists

1. User enters project name
2. Auto-generated slug conflicts with existing project
3. System shows error: "This project URL is already taken"
4. User manually edits slug to unique value
5. System validates new slug
6. Continue from step 6 of main flow

A2: Quota Exceeded

1. User attempts to create project
2. System detects account has reached project limit
3. System shows error: "Project quota exceeded"
4. System suggests upgrade or deletion of existing projects
5. Use case ends

A3: Permission Denied

1. User attempts to create project
2. System detects user lacks projects.create permission
3. System shows error: "Permission denied"
4. Use case ends

Business Rules

Implementation

// Command
interface CreateProjectCommand {
  accountId: string;
  name: string;
  slug: string;
  description?: string;
  geometry?: GeoJSON.Geometry;
}

// Use Case
class CreateProjectUseCase {
  async execute(command: CreateProjectCommand): Promise<Result<Project, ProjectError>> {
    // 1. Check quota
    const quotaResult = await this.usageService.checkQuota(command.accountId, 'project');
    if (!quotaResult.ok) return quotaResult;
    
    // 2. Validate slug uniqueness
    const slugExists = await this.projectRepository.slugExists(command.accountId, command.slug);
    if (slugExists) {
      return Result.err(new ProjectSlugAlreadyExistsError(command.slug));
    }
    
    // 3. Create project
    const project = Project.create(command);
    const result = await this.projectRepository.create(project);
    
    // 4. Track usage
    if (result.ok) {
      await this.usageService.track({
        accountId: command.accountId,
        type: 'project',
        amount: 1,
      });
    }
    
    return result;
  }
}

UC-002: Update Project

Description

User updates project details including name, slug, description, and settings. System validates permissions, checks slug uniqueness, updates the record, and logs changes.

Actors

• Primary: Authenticated User
• Secondary: Audit System

Preconditions

• User is authenticated
• Project exists
• User has permission to update the project

Postconditions

• Project updated with new data
• Slug updated if changed (and unique)
• Audit log entry created
• Cache invalidated

Main Flow

1. User navigates to project settings
2. User modifies project details:
   • Updates name
   • Optionally changes slug
   • Updates description
3. User clicks "Save Changes"
4. System validates new data
5. If slug changed, system checks uniqueness
6. System updates project record
7. System logs change to audit log
8. System invalidates cache
9. User sees success message

Alternative Flows

A1: Slug Already Exists

1. User changes slug to existing value
2. System shows error: "Slug already in use"
3. User provides different slug
4. Continue from step 5 of main flow

A2: Project Not Found

1. User attempts to access non-existent project
2. System shows 404 error
3. Use case ends

Business Rules

UC-003: Archive Project

Description

User archives a project to hide it from default views while preserving all data. Archived projects can be restored at any time.

Actors

• Primary: Authenticated User

Preconditions

• User is authenticated
• Project exists and is active
• User has permission to archive the project

Postconditions

• Project marked as archived
• Project hidden from default project lists
• Usage tracking paused
• All project data preserved

Main Flow

1. User navigates to project settings
2. User clicks "Archive Project"
3. System shows confirmation dialog:
   • "Are you sure you want to archive this project?"
   • "Archived projects are hidden but can be restored."
4. User confirms action
5. System marks project as archived
6. System pauses usage tracking
7. User is redirected to projects list
8. Success message: "Project archived successfully"

Alternative Flows

A1: User Cancels

1. User clicks "Archive Project"
2. System shows confirmation dialog
3. User clicks "Cancel"
4. Use case ends, no changes made

Business Rules

UC-004: Restore Project

Description

User restores an archived project back to active state.

Actors

• Primary: Authenticated User

Preconditions

• Project exists and is archived
• User has permission to restore the project
• Account has available quota

Postconditions

• Project marked as active
• Project visible in default project lists
• Usage tracking resumed

Main Flow

1. User navigates to archived projects view
2. User locates the archived project
3. User clicks "Restore Project"
4. System checks account quota
5. System marks project as active
6. System resumes usage tracking
7. Success message: "Project restored successfully"

Alternative Flows

A1: Quota Exceeded

1. User attempts to restore project
2. System detects account has reached project limit
3. System shows error: "Cannot restore - project quota exceeded"
4. System suggests archiving another project or upgrading
5. Use case ends

Business Rules

UC-005: Delete Project

Description

User permanently deletes a project. System validates permissions, checks for dependencies, performs soft delete, and schedules cleanup.

Actors

• Primary: Authenticated User
• Secondary: Usage Tracking System, Cleanup System

Preconditions

• User is authenticated
• Project exists and is not already deleted
• User has permission to delete the project

Postconditions

• Project marked as deleted (soft delete)
• Project slug released for reuse after 30 days
• Associated resources marked for cleanup
• Usage tracking stopped
• Audit log entry created

Main Flow

1. User navigates to project settings
2. User clicks "Delete Project"
3. System shows confirmation dialog with warnings:
   • "This action cannot be undone"
   • "All project data will be permanently deleted"
   • Lists associated resources (assets, documents, etc.)
4. User types project name to confirm
5. User clicks "Delete Permanently"
6. System performs soft delete
7. System schedules resource cleanup (30 days)
8. System stops usage tracking
9. System logs deletion to audit log
10. User is redirected to projects list

Alternative Flows

A1: Has Active Dependencies

1. User attempts to delete project
2. System detects active assets/documents
3. System shows warning: "Project has X assets and Y documents"
4. User chooses: cancel or force delete
5. If force, continue to step 6
6. If cancel, use case ends

A2: Already Deleted

1. User attempts to access deleted project
2. System shows error: "Project not found"
3. Use case ends

Business Rules

UC-006: Slug Auto-Generation

Description

System automatically generates URL-friendly slugs from project names.

Scenarios

Scenario A: Simple Name

• Input: John Doe
• Output: john-doe
• Process:
  1. Convert to lowercase: john doe
  2. Replace spaces with hyphens: john-doe

Scenario B: Name with Special Characters

• Input: João Silva & Co.
• Output: joao-silva-co
• Process:
  1. Convert to lowercase: joão silva & co.
  2. Remove accents: joao silva & co.
  3. Remove special chars: joao silva co
  4. Replace spaces with hyphens: joao-silva-co

Scenario C: Name with Multiple Spaces

• Input: Tech Solutions Inc
• Output: tech-solutions-inc
• Process:
  1. Convert to lowercase
  2. Replace multiple spaces with single hyphen

Scenario D: Very Long Name

• Input: 300-character project name
• Output: Truncated to 128 characters
• Process:
  1. Generate slug normally
  2. Truncate at word boundary if possible
  3. Remove trailing hyphen

Business Rules

Testing Checklist

Create Project

• Auto-generation works from name field
• Manual edit disables auto-generation
• Validation shows spinner while checking
• Green checkmark for available slug
• Red X for taken slug
• Debounce works (no validation spam)
• Unique slugs per account (not global)
• Handles special characters correctly
• Truncates long slugs to 128 chars
• Create button disabled until slug validated

Update Project

• All fields editable
• Slug change validates uniqueness
• Success message after save
• Audit log entry created

Archive/Restore

• Archive confirmation dialog
• Archived projects hidden from default view
• Restore checks quota
• Usage tracking paused/resumed correctly

Delete Project

• Confirmation requires typing project name
• Soft delete preserves data for 30 days
• Hard delete after 30 days
• Associated resources cleaned up

Related Documentation

• Team Collaboration Use Cases
• Asset Tracking Use Cases
• Database Architecture