clickup-reference-architecture

# ClickUp Reference Architecture

## Overview

Production-ready architecture for ClickUp API v2 integrations covering custom fields, time tracking, goals, and two-way sync with external systems.

## Architecture Layers

```
┌──────────────────────────────────────────┐
│          Application Layer               │
│   (Routes, Controllers, Webhooks)        │
├──────────────────────────────────────────┤
│          Service Layer                   │
│   (Business Logic, Orchestration)        │
├──────────────────────────────────────────┤
│          ClickUp Client Layer            │
│   (API Wrapper, Types, Cache, Retry)     │
├──────────────────────────────────────────┤
│          Infrastructure                  │
│   (Queue, Cache, Monitoring, Secrets)    │
└──────────────────────────────────────────┘
          │
          ▼
  api.clickup.com/api/v2/
```

## Custom Fields API

Custom fields let you extend tasks beyond built-in fields. Each field has a UUID and a type.

```
GET  /api/v2/list/{list_id}/field          Get accessible custom fields
POST /api/v2/task/{task_id}/field/{field_id}  Set custom field value
DELETE /api/v2/task/{task_id}/field/{field_id}  Remove custom field value
```

### Custom Field Types and Value Formats

| Type | `value` Format | Example |
|------|---------------|---------|
| `text` | string | `"Release v2.1"` |
| `number` | number | `42` |
| `money` / `currency` | number (in smallest unit) | `9999` (= $99.99) |
| `date` | Unix ms timestamp | `1695000000000` |
| `drop_down` | option UUID from `type_config.options` | `"opt_uuid_123"` |
| `labels` | array of label UUIDs | `["lbl_uuid_1", "lbl_uuid_2"]` |
| `checkbox` | boolean | `true` |
| `email` | string | `"user@example.com"` |
| `phone` | string | `"+1-555-0100"` |
| `url` | string | `"https://example.com"` |
| `rating` | number (0-5) | `4` |
| `location` | object | `{ "lat": 33.749, "lng": -84.388 }` |

```typescript
// Get custom fields for a list
const fields = await clickupRequest(`/list/${listId}/field`);
// Response: { fields: [{ id: "uuid", name: "Sprint", type: "drop_down", type_config: { options: [...] } }] }

// Set a dropdown custom field
const sprintField = fields.fields.find((f: any) => f.name === 'Sprint');
const nextSprint = sprintField.type_config.options.find((o: any) => o.name === 'Sprint 24');

await clickupRequest(`/task/${taskId}/field/${sprintField.id}`, {
  method: 'POST',
  body: JSON.stringify({ value: nextSprint.orderindex }),
});

// Set a date custom field
await clickupRequest(`/task/${taskId}/field/${dateFieldId}`, {
  method: 'POST',
  body: JSON.stringify({ value: Date.now() + 604800000 }), // 1 week from now
});
```

## Time Tracking API

```
POST   /api/v2/team/{team_id}/time_entries     Create time entry
GET    /api/v2/team/{team_id}/time_entries     Get time entries (date range)
GET    /api/v2/team/{team_id}/time_entries/current  Get running timer
GET    /api/v2/task/{task_id}/time             Get tracked time on task
PUT    /api/v2/team/{team_id}/time_entries/{timer_id}  Update entry
DELETE /api/v2/team/{team_id}/time_entries/{timer_id}  Delete entry
```

```typescript
// Create a time entry (logged time)
await clickupRequest(`/team/${teamId}/time_entries`, {
  method: 'POST',
  body: JSON.stringify({
    task_id: 'abc123',
    description: 'Worked on auth module',
    start: Date.now() - 3600000, // 1 hour ago
    duration: 3600000,           // 1 hour in ms
    assignee: 183,               // user ID
    billable: true,
  }),
});

// Get entries for a date range (default: last 30 days)
const entries = await clickupRequest(
  `/team/${teamId}/time_entries?start_date=${startMs}&end_date=${endMs}`
);
// Note: negative duration means timer is currently running
```

## Goals API

```
POST   /api/v2/team/{team_id}/goal         Create goal
GET    /api/v2/team/{team_id}/goal         Get goals
GET    /api/v2/goal/{goal_id}              Get goal
PUT    /api/v2/goal/{goal_id}              Update goal
DELETE /api/v2/goal/{goal_id}              Delete goal
POST   /api/v2/goal/{goal_id}/key_result   Create key result
PUT    /api/v2/key_result/{key_result_id}  Update key result
DELETE /api/v2/key_result/{key_result_id}  Delete key result
```

```typescript
// Create a goal with key results
const goal = await clickupRequest(`/team/${teamId}/goal`, {
  method: 'POST',
  body: JSON.stringify({
    name: 'Q1 2026 Engineering OKRs',
    due_date: 1711929600000,
    description: 'Engineering team quarterly objectives',
    multiple_owners: true,
    owners: [183, 456],
    color: '#05a1f5',
  }),
});

// Add a key result (target)
await clickupRequest(`/goal/${goal.goal.id}/key_result`, {
  method: 'POST',
  body: JSON.stringify({
    name: 'Reduce P95 latency to <200ms',
    type: 'number',
    steps_start: 500,
    steps_end: 200,
    unit: 'ms',
    owners: [183],
  }),
});
```

## Two-Way Sync Pattern

```typescript
// Sync ClickUp tasks to external system and vice versa
class ClickUpSyncService {
  async syncToExternal(listId: string) {
    const { tasks } = await clickupRequest(`/list/${listId}/task?archived=false`);

    for (const task of tasks) {
      await externalSystem.upsert({
        externalId: task.id,
        title: task.name,
        status: this.mapStatus(task.status.status),
        assignee: task.assignees[0]?.email,
        updatedAt: parseInt(task.date_updated),
      });
    }
  }

  async syncFromExternal(externalItem: ExternalItem) {
    if (externalItem.clickupTaskId) {
      await clickupRequest(`/task/${externalItem.clickupTaskId}`, {
        method: 'PUT',
        body: JSON.stringify({
          name: externalItem.title,
          status: this.reverseMapStatus(externalItem.status),
        }),
      });
    }
  }

  private mapStatus(clickupStatus: string): string {
    const map: Record<string, string> = {
      'to do': 'backlog', 'in progress': 'active',
      'review': 'in_review', 'complete': 'done',
    };
    return map[clickupStatus] ?? 'backlog';
  }
}
```

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| Custom field UUID not found | Field removed or renamed | Re-fetch fields via `/list/{id}/field` |
| Time entry negative duration | Timer still running | Stop timer before reading duration |
| Goal permission denied | User not goal owner | Add user to goal owners |
| Sync conflict | Both sides updated | Last-write-wins or manual merge |

## Resources

- [Custom Fields Docs](https://developer.clickup.com/docs/customfields)
- [Set Custom Field Value](https://developer.clickup.com/reference/setcustomfieldvalue)
- [Time Tracking Endpoints](https://developer.clickup.com/reference/createatimeentry)
- [ClickUp Developer Portal](https://developer.clickup.com/)

## Next Steps

For multi-environment setup, see `clickup-multi-env-setup`.