# Activity Module: ERD & UX Flow

## Entity Relationship Diagram (ERD)

### Overview

The Activity module manages scheduled events, their occurrences, assigned users, and types. It integrates with the Pipeline module (optional) and User management.

### Tables

#### 1. `activities`

Stores master activity definitions.

| Column             | Type               | Constraints                            | Description                    |
| ------------------ | ------------------ | -------------------------------------- | ------------------------------ |
| `id`               | `uuid` (or `ulid`) | PRIMARY KEY                            | Unique identifier              |
| `title`            | `varchar(255)`     | NOT NULL                               | Activity title                 |
| `description`      | `text`             | NULLABLE                               | Detailed description           |
| `activity_type_id` | `uuid`             | FOREIGN KEY → `activity_types.id`      | Type of activity               |
| `pipeline_id`      | `uuid`             | NULLABLE, FOREIGN KEY → `pipelines.id` | Associated pipeline (optional) |
| `created_by`       | `uuid`             | FOREIGN KEY → `users.id`               | User who created the activity  |
| `created_at`       | `timestamp`        | DEFAULT CURRENT_TIMESTAMP              |                                |
| `updated_at`       | `timestamp`        | DEFAULT CURRENT_TIMESTAMP              |                                |

#### 2. `activity_types`

Lookup table for activity categories.

| Column       | Type           | Constraints               | Description                     |
| ------------ | -------------- | ------------------------- | ------------------------------- |
| `id`         | `uuid`         | PRIMARY KEY               | Unique identifier               |
| `type`       | `varchar(100)` | NOT NULL, UNIQUE          | Name of type                    |
| `color`      | `varchar(7)`   | NULLABLE                  | Hex color code for UI (#RRGGBB) |
| `created_at` | `timestamp`    | DEFAULT CURRENT_TIMESTAMP |                                 |
| `updated_at` | `timestamp`    | DEFAULT CURRENT_TIMESTAMP |                                 |

#### 3. `activity_occurrences`

Represents scheduled instances of an activity (supports recurring events).

| Column           | Type        | Constraints                   | Description              |
| ---------------- | ----------- | ----------------------------- | ------------------------ |
| `id`             | `uuid`      | PRIMARY KEY                   | Unique identifier        |
| `activity_id`    | `uuid`      | FOREIGN KEY → `activities.id` | Parent activity          |
| `start_datetime` | `timestamp` | NOT NULL                      | Start time of occurrence |
| `end_datetime`   | `timestamp` | NOT NULL                      | End time of occurrence   |
| `created_at`     | `timestamp` | DEFAULT CURRENT_TIMESTAMP     |                          |
| `updated_at`     | `timestamp` | DEFAULT CURRENT_TIMESTAMP     |                          |

#### 4. `activity_users`

Junction table assigning users to activities with a specific role.

| Column        | Type        | Constraints                   | Description                                                      |
| ------------- | ----------- | ----------------------------- | ---------------------------------------------------------------- |
| `id`          | `uuid`      | PRIMARY KEY                   | Unique identifier                                                |
| `activity_id` | `uuid`      | FOREIGN KEY → `activities.id` | Reference to activity                                            |
| `user_id`     | `uuid`      | FOREIGN KEY → `users.id`      | Assigned user                                                    |
| `role_id`     | `uuid`      | FOREIGN KEY → `roles.id`      | Role of user in this activity (e.g., "Organizer", "Participant") |
| `created_at`  | `timestamp` | DEFAULT CURRENT_TIMESTAMP     |                                                                  |

### Relationships

- **activities** → **activity_types**: Many‑to‑One (`activity_type_id`)
- **activities** → **pipelines**: Many‑to‑One, optional (`pipeline_id`)
- **activities** → **users**: Many‑to‑One (`created_by`)
- **activity_occurrences** → **activities**: Many‑to‑One (`activity_id`)
- **activity_users** → **activities**: Many‑to‑One (`activity_id`)
- **activity_users** → **users**: Many‑to‑One (`user_id`)
- **activity_users** → **roles**: Many‑to‑One (`role_id`)

### Mermaid ERD Diagram

```mermaid
erDiagram
    activities {
        uuid id PK
        varchar title
        text description
        uuid activity_type_id FK
        uuid pipeline_id FK
        uuid created_by FK
        timestamp created_at
        timestamp updated_at
    }

    activity_types {
        uuid id PK
        varchar type
        varchar color
        timestamp created_at
        timestamp updated_at
    }

    activity_occurrences {
        uuid id PK
        uuid activity_id FK
        timestamp start_datetime
        timestamp end_datetime
        timestamp created_at
        timestamp updated_at
    }

    activity_users {
        uuid id PK
        uuid activity_id FK
        uuid user_id FK
        uuid role_id FK
        timestamp created_at
    }

    users {
        uuid id PK
        varchar name
    }

    pipelines {
        uuid id PK
        varchar name
    }

    roles {
        uuid id PK
        varchar name
    }

    activities }o--|| activity_types : "belongs to"
    activities }o--o| pipelines : "optional pipeline"
    activities }|--|| users : "created by"
    activity_occurrences }|--|| activities : "occurrence of"
    activity_users }|--|| activities : "assigned to"
    activity_users }|--|| users : "user"
    activity_users }|--|| roles : "role"
```

---

## UX Flow

### User Journey: Creating & Managing Activities

#### 1. **Activity List View**

- **Screen**: Dashboard or dedicated Activity page.
- **Elements**:
  - Table/grid of activities with columns: Title, Type, Pipeline, Start/End, Status.
  - Filter by type, pipeline, date range, assigned user.
  - Button “+ New Activity” to create.
- **User Actions**:
  - Click on activity row to view details.
  - Use filters to narrow list.
  - Click “New Activity” to proceed to creation.

#### 2. **Create Activity**

- **Screen**: Modal or separate form page.
- **Form Fields**:
  - Title (required)
  - Description (textarea)
  - Activity Type (dropdown populated from `activity_types`)
  - Pipeline (optional dropdown from pipelines)
  - Assign Users (multi‑select with role dropdown per user)
  - Schedule:
    - Single occurrence: start & end datetime picker.
    - Recurring pattern (future enhancement).
- **Validation**:
  - Title must be unique? (optional)
  - End date after start date.
- **Submit**: Saves activity and creates first occurrence (if single) or series.

#### 3. **Activity Detail View**

- **Screen**: After creation or from list click.
- **Sections**:
  - Header: Title, type badge with color, pipeline link.
  - Description.
  - Assigned users with roles.
  - Occurrences table (upcoming/past) with actions (edit, delete, mark complete).
  - Timeline of changes (audit log).
- **Actions**:
  - Edit activity (opens edit form).
  - Add new occurrence.
  - Delete activity (with confirmation).

#### 4. **Edit Occurrence**

- **Screen**: Inline edit or modal.
- **Fields**: Start/End datetime, status dropdown.
- **Save**: Updates the occurrence.

#### 5. **Notifications & Reminders**

- **System Triggers**:
  - Email/in‑app notification to assigned users when activity is created or updated.
  - Reminder X minutes before start (configurable).
- **Integration**: Use Laravel notifications + queue.

### Flowchart

```mermaid
flowchart TD
    A[User accesses Activity List] --> B{Action?}
    B -->|Create New| C[Open Create Form]
    B -->|View Details| D[Load Activity Detail]
    B -->|Filter/Search| E[Apply Filters]

    C --> F[Fill Form]
    F --> G{Validate}
    G -->|Invalid| H[Show Errors]
    H --> C
    G -->|Valid| I[Save Activity & Occurrence]
    I --> J[Show Success Message]
    J --> D

    D --> K{User Action}
    K -->|Edit Activity| L[Open Edit Form]
    K -->|Add Occurrence| M[Open Occurrence Form]
    K -->|Delete Activity| N[Confirm Deletion]
    N -->|Yes| O[Delete & Redirect to List]
    N -->|No| D
    L --> P[Update Activity]
    P --> D
    M --> Q[Save New Occurrence]
    Q --> D

    E --> A
```

### Integration Points

- **Pipeline Module**: If pipeline is selected, activity appears in pipeline’s activity tab.
- **User Permissions**: Only users with “activity.write” permission can create/edit. Role‑based access via `activity_users`.
- **Calendar View**: Future enhancement – display occurrences in a calendar (FullCalendar integration).
- **Reporting**: Activities can be aggregated in dashboard widgets (count by type, completion rate).

### Mobile Considerations

- Form inputs should be touch‑friendly (larger tap targets).
- Date‑time picker uses native mobile datetime input.
- Responsive table → card list on small screens.

---

## Implementation Notes

### Backend (Laravel)

- Models: `Activity`, `ActivityType`, `ActivityOccurrence`, `ActivityUser`.
- Controllers: `ActivityController`, `ActivityOccurrenceController`.
- Validators: `ActivityValidator`, `ActivityOccurrenceValidator`.
- Database migrations for the four tables.

### Frontend (React)

- Pages: `ActivityList`, `ActivityDetail`, `ActivityForm`.
- Components: `ActivityTable`, `UserAssignment`, `OccurrenceEditor`.
- State: Redux slices for activities, occurrences, types.
- API calls via Axios to Laravel endpoints.

### Security

- JWT authentication required.
- Permission middleware: `EnsureUserHasPermission` for activity operations.
- Ownership: users can only edit activities they created or are assigned to (if policy enforced).

---

_Document generated on 2026‑03‑31._