| name | clickup-reference-architecture |
| description | Production architecture for ClickUp API v2 integrations with layered design,
custom fields, time tracking, goals, and two-way sync patterns.
Trigger: "clickup architecture", "clickup design", "clickup project structure",
"clickup custom fields", "clickup time tracking", "clickup goals API".
|
| allowed-tools | Read, Grep |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","clickup"] |
| compatible-with | claude-code |
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" |
|
