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 | `1695000000...