clickup-reference-architecture
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".
- License 许可
- MIT
- 最近更新
- 2026-07-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- clickup-reference-architecture
- tags
- [ "saas", "productivity", "clickup" ]
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- 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
- compatible-with
- claude-code
03 SKILL.md 正文
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 } |
// 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
// 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
// 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
// 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
Next Steps
For multi-environment setup, see clickup-multi-env-setup.
04 同仓库更多 Skills
zustand-store-creator
Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".
zero-trust-config-helper
Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".
zapier-integration-helper
Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".
yaml-config-validator
Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".
xvary-stock-research
Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).
xss-vulnerability-scanner
Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".