stack/docs/4-api/3-activity-logging/README.md

# Activity Logging API

The Activity Logging API provides comprehensive audit trail and activity tracking functionality for the Mosaic Stack platform. It logs user actions, workspace changes, task/event modifications, and authentication events.

## Overview

Activity logs are automatically created for:

- **CRUD Operations**: Task, event, project, and workspace modifications
- **Authentication Events**: Login, logout, password resets
- **User Actions**: Task assignments, workspace member changes
- **System Events**: Configuration updates, permission changes

All activity logs are workspace-scoped and support multi-tenant isolation through Row-Level Security (RLS).

## Endpoints

### List Activity Logs

```
GET /api/activity
```

Get a paginated list of activity logs with optional filters.

**Query Parameters:**

| Parameter     | Type           | Required | Description                                    |
| ------------- | -------------- | -------- | ---------------------------------------------- |
| `workspaceId` | UUID           | Yes      | Workspace to filter by                         |
| `userId`      | UUID           | No       | Filter by user who performed the action        |
| `action`      | ActivityAction | No       | Filter by action type (CREATED, UPDATED, etc.) |
| `entityType`  | EntityType     | No       | Filter by entity type (TASK, EVENT, etc.)      |
| `entityId`    | UUID           | No       | Filter by specific entity                      |
| `startDate`   | ISO 8601       | No       | Filter activities after this date              |
| `endDate`     | ISO 8601       | No       | Filter activities before this date             |
| `page`        | Number         | No       | Page number (default: 1)                       |
| `limit`       | Number         | No       | Items per page (default: 50, max: 100)         |

**Response:**

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
      "userId": "770e8400-e29b-41d4-a716-446655440002",
      "action": "CREATED",
      "entityType": "TASK",
      "entityId": "880e8400-e29b-41d4-a716-446655440003",
      "details": {
        "title": "New Task",
        "status": "NOT_STARTED"
      },
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2024-01-28T12:00:00Z",
      "user": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 50,
    "totalPages": 3
  }
}
```

**Example Requests:**

```bash
# Get all activities in a workspace
GET /api/activity?workspaceId=660e8400-e29b-41d4-a716-446655440001

# Get activities for a specific user
GET /api/activity?workspaceId=660e8400-e29b-41d4-a716-446655440001&userId=770e8400-e29b-41d4-a716-446655440002

# Get task creation events
GET /api/activity?workspaceId=660e8400-e29b-41d4-a716-446655440001&action=CREATED&entityType=TASK

# Get activities in date range
GET /api/activity?workspaceId=660e8400-e29b-41d4-a716-446655440001&startDate=2024-01-01&endDate=2024-01-31

# Paginate results
GET /api/activity?workspaceId=660e8400-e29b-41d4-a716-446655440001&page=2&limit=25
```

---

### Get Single Activity Log

```
GET /api/activity/:id
```

Retrieve a single activity log entry by ID.

**Path Parameters:**

| Parameter | Type | Required | Description     |
| --------- | ---- | -------- | --------------- |
| `id`      | UUID | Yes      | Activity log ID |

**Query Parameters:**

| Parameter     | Type | Required | Description                               |
| ------------- | ---- | -------- | ----------------------------------------- |
| `workspaceId` | UUID | Yes      | Workspace ID (for multi-tenant isolation) |

**Response:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
  "userId": "770e8400-e29b-41d4-a716-446655440002",
  "action": "UPDATED",
  "entityType": "TASK",
  "entityId": "880e8400-e29b-41d4-a716-446655440003",
  "details": {
    "changes": {
      "status": "IN_PROGRESS"
    }
  },
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "createdAt": "2024-01-28T12:00:00Z",
  "user": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

**Example Request:**

```bash
GET /api/activity/550e8400-e29b-41d4-a716-446655440000?workspaceId=660e8400-e29b-41d4-a716-446655440001
```

---

### Get Entity Audit Trail

```
GET /api/activity/audit/:entityType/:entityId
```

Retrieve complete audit trail for a specific entity (task, event, project, etc.).

**Path Parameters:**

| Parameter    | Type       | Required | Description                                            |
| ------------ | ---------- | -------- | ------------------------------------------------------ |
| `entityType` | EntityType | Yes      | Type of entity (TASK, EVENT, PROJECT, WORKSPACE, USER) |
| `entityId`   | UUID       | Yes      | Entity ID                                              |

**Query Parameters:**

| Parameter     | Type | Required | Description                               |
| ------------- | ---- | -------- | ----------------------------------------- |
| `workspaceId` | UUID | Yes      | Workspace ID (for multi-tenant isolation) |

**Response:**

Returns array of activity logs in chronological order (oldest first).

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
    "userId": "770e8400-e29b-41d4-a716-446655440002",
    "action": "CREATED",
    "entityType": "TASK",
    "entityId": "880e8400-e29b-41d4-a716-446655440003",
    "details": {
      "title": "New Task"
    },
    "createdAt": "2024-01-28T10:00:00Z",
    "user": {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440004",
    "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
    "userId": "770e8400-e29b-41d4-a716-446655440005",
    "action": "UPDATED",
    "entityType": "TASK",
    "entityId": "880e8400-e29b-41d4-a716-446655440003",
    "details": {
      "changes": {
        "status": "IN_PROGRESS"
      }
    },
    "createdAt": "2024-01-28T12:00:00Z",
    "user": {
      "id": "770e8400-e29b-41d4-a716-446655440005",
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  }
]
```

**Example Requests:**

```bash
# Get audit trail for a task
GET /api/activity/audit/TASK/880e8400-e29b-41d4-a716-446655440003?workspaceId=660e8400-e29b-41d4-a716-446655440001

# Get audit trail for a project
GET /api/activity/audit/PROJECT/990e8400-e29b-41d4-a716-446655440006?workspaceId=660e8400-e29b-41d4-a716-446655440001

# Get audit trail for a workspace
GET /api/activity/audit/WORKSPACE/660e8400-e29b-41d4-a716-446655440001?workspaceId=660e8400-e29b-41d4-a716-446655440001
```

---

## Enums

### ActivityAction

Actions that can be logged:

- `CREATED` - Entity was created
- `UPDATED` - Entity was updated
- `DELETED` - Entity was deleted
- `COMPLETED` - Task or project was completed
- `ASSIGNED` - Task was assigned to a user
- `COMMENTED` - Comment was added (future use)
- `LOGIN` - User logged in
- `LOGOUT` - User logged out
- `PASSWORD_RESET` - Password was reset
- `EMAIL_VERIFIED` - Email was verified

### EntityType

Types of entities that can be tracked:

- `TASK` - Task entity
- `EVENT` - Calendar event
- `PROJECT` - Project
- `WORKSPACE` - Workspace
- `USER` - User profile

---

## Automatic Logging

The Activity Logging system includes an interceptor that automatically logs:

- **POST requests** → `CREATED` action
- **PATCH/PUT requests** → `UPDATED` action
- **DELETE requests** → `DELETED` action

The interceptor extracts:

- User information from the authenticated session
- Workspace context from request
- IP address and user agent from HTTP headers
- Entity ID from route parameters or response

---

## Manual Logging

For custom logging scenarios, use the `ActivityService` helper methods:

```typescript
import { ActivityService } from "@/activity/activity.service";

@Injectable()
export class TaskService {
  constructor(private activityService: ActivityService) {}

  async createTask(data, userId, workspaceId) {
    const task = await this.prisma.task.create({ data });

    // Log task creation
    await this.activityService.logTaskCreated(workspaceId, userId, task.id, { title: task.title });

    return task;
  }
}
```

### Available Helper Methods

#### Task Activities

- `logTaskCreated(workspaceId, userId, taskId, details?)`
- `logTaskUpdated(workspaceId, userId, taskId, details?)`
- `logTaskDeleted(workspaceId, userId, taskId, details?)`
- `logTaskCompleted(workspaceId, userId, taskId, details?)`
- `logTaskAssigned(workspaceId, userId, taskId, assigneeId)`

#### Event Activities

- `logEventCreated(workspaceId, userId, eventId, details?)`
- `logEventUpdated(workspaceId, userId, eventId, details?)`
- `logEventDeleted(workspaceId, userId, eventId, details?)`

#### Project Activities

- `logProjectCreated(workspaceId, userId, projectId, details?)`
- `logProjectUpdated(workspaceId, userId, projectId, details?)`
- `logProjectDeleted(workspaceId, userId, projectId, details?)`

#### Workspace Activities

- `logWorkspaceCreated(workspaceId, userId, details?)`
- `logWorkspaceUpdated(workspaceId, userId, details?)`
- `logWorkspaceMemberAdded(workspaceId, userId, memberId, role)`
- `logWorkspaceMemberRemoved(workspaceId, userId, memberId)`

#### User Activities

- `logUserUpdated(workspaceId, userId, details?)`

---

## Security & Privacy

### Multi-Tenant Isolation

All activity logs are scoped to workspaces using Row-Level Security (RLS). Users can only access activity logs for workspaces they belong to.

### Data Retention

Activity logs are retained indefinitely by default. Consider implementing a retention policy based on:

- Compliance requirements
- Storage constraints
- Business needs

### Sensitive Data

Activity logs should NOT contain:

- Passwords or authentication tokens
- Credit card information
- Personal health information
- Other sensitive PII

Store only metadata needed for audit purposes. Use the `details` field for non-sensitive context.

---

## Best Practices

### 1. Use Descriptive Details

Include enough context to understand what changed:

```typescript
// Good
await activityService.logTaskUpdated(workspaceId, userId, taskId, {
  changes: {
    status: { from: "NOT_STARTED", to: "IN_PROGRESS" },
    assignee: { from: null, to: "user-456" },
  },
});

// Less useful
await activityService.logTaskUpdated(workspaceId, userId, taskId);
```

### 2. Log Business-Critical Actions

Prioritize logging actions that:

- Change permissions or access control
- Delete data
- Modify billing or subscription
- Export data
- Change security settings

### 3. Query Efficiently

Use appropriate filters to reduce data transfer:

```typescript
// Efficient - filters at database level
const activities = await fetch("/api/activity?workspaceId=xxx&entityType=TASK&page=1&limit=50");

// Inefficient - transfers all data then filters
const activities = await fetch("/api/activity?workspaceId=xxx");
const taskActivities = activities.filter((a) => a.entityType === "TASK");
```

### 4. Display User-Friendly Activity Feeds

Transform activity logs into human-readable messages:

```typescript
function formatActivityMessage(activity: ActivityLog) {
  const { user, action, entityType, details } = activity;

  switch (action) {
    case "CREATED":
      return `${user.name} created ${entityType.toLowerCase()} "${details.title}"`;
    case "UPDATED":
      return `${user.name} updated ${entityType.toLowerCase()}`;
    case "DELETED":
      return `${user.name} deleted ${entityType.toLowerCase()}`;
    default:
      return `${user.name} performed ${action}`;
  }
}
```

---

## Error Handling

Activity logging failures should NOT block the primary operation. The interceptor and service methods handle errors gracefully:

```typescript
try {
  await activityService.logActivity(data);
} catch (error) {
  // Log error but don't throw
  logger.error("Failed to log activity", error);
}
```

If activity logging is critical for compliance, implement synchronous validation before the operation completes.

---

## Performance Considerations

### Indexing

The following indexes optimize common queries:

- `workspaceId` - Filter by workspace
- `workspaceId + createdAt` - Recent activities per workspace
- `entityType + entityId` - Audit trail queries
- `userId` - User activity history
- `action` - Filter by action type

### Pagination

Always use pagination for activity queries. Default limit is 50 items, maximum is 100.

### Background Processing

For high-volume systems, consider:

- Async activity logging with message queues
- Batch inserts for multiple activities
- Separate read replicas for reporting

---

## Related Documentation

- [Authentication API](../2-authentication/README.md)
- [API Conventions](../1-conventions/README.md)
- [Database Schema](../../3-architecture/2-database/README.md)