clickup-reference-architecture

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 <[e-mail]>
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	"[e-mail]"