obsidian/01 Projects/DevOps_Click_UP_sync/DEVELOPER_MANUAL.md

auto_generated	created	manual_updated_at	modified	name	status	tags	type
true	2026-05-18	2026-05-18	2026-05-18	Developer_Manual	active	domain/devops status/active tech/azure-ad tech/docker tech/fastapi tech/python tech/sqlite type/sop	sop

DevOps ↔ ClickUp Sync Developer Manual

Architecture Overview

The application is a FastAPI-based microservice that listens for webhooks from Azure DevOps and ClickUp. It processes these events, determines the direction of sync, and updates the respective API. A SQLite database persists the mapping between entity IDs to prevent duplicate creation and ensure referential integrity.

Tech Stack

• Framework: FastAPI (Python 3.10+)
• Database: SQLite (via aiosqlite for async support)
• ORM: SQLAlchemy (Async)
• HTTP Client: httpx
• Configuration: Pydantic Settings
• Deployment: Docker / Docker Compose

Local Setup

1. Prerequisites

• Python 3.10+
• Docker & Docker Compose

2. Installation

# Clone the repo
git clone <repo-url>
cd devops-clickup-sync

# Install dependencies
pip install -r requirements.txt

# Copy env file
cp .env.example .env

# Edit .env with your credentials

3. Run Locally

# Using Python directly
uvicorn src.main:app --reload --host 0.0.0.0 --port 8080

# Or using Docker
docker-compose up -d

Environment Variables

See .env.example for all required variables.

• ADO_PAT: Personal Access Token for Azure DevOps (Scope: Work Item (Read & Write), Code (Read)).
• CLICKUP_API_TOKEN: Private App token from ClickUp (Scope: Write for tasks/comments).
• WEBHOOK_SECRET: Used to validate incoming webhooks.
• DATABASE_URL: Defaults to local SQLite. Change to PostgreSQL/MySQL URI for production.

Key Services & Entry Points

src/main.py

• Entry Point: Initializes FastAPI app, lifespan events (DB init), and mounts routers.
• Routers:
  • webhook_router: Handles incoming POST requests from ADO/ClickUp.
  • dashboard_router: Serves /api/health, /api/status.
  • setup_router: Manages mapping configurations.

src/database.py

• Models:
  • SyncMap: Links ado_work_item_id to clickup_task_id.
  • ProjectMap: Maps ADO Projects/Areas to ClickUp Spaces/Lists.
  • CommentMap: Links ado_comment_id to clickup_comment_id.
  • SyncLog: Audit trail for sync events.
• Init: init_db() creates tables if they don't exist.

src/clients/ado.py

• ADOClient: Wraps Azure DevOps REST API.
• Key methods: get_work_item, update_work_item, create_work_item.

src/clients/clickup.py

• ClickUpClient: Wraps ClickUp API v2.
• Key methods: get_task, update_task, create_task, get_spaces/lists.

API Reference

Webhooks

• Method: POST
• URL: PUBLIC_URL/webhook (or configured route)
• Headers: X-Webhook-Secret must match WEBHOOK_SECRET.
• Body: JSON Payload from ADO (src/models/ado.py) or ClickUp (src/models/clickup.py).

Dashboard API

• GET /api/health: Returns {"status": "ok"}.
• GET /api/status: Returns counts of synced items, comment maps, and recent sync log statuses.

Deployment

Docker Compose

The docker-compose.yml defines the service:

• Port 8080 exposed.
• Data persisted in ./data volume.
• Healthcheck configured on /api/health.

Production Considerations

1. Database: Switch DATABASE_URL to a managed PostgreSQL instance. Migrate SQLAlchemy models accordingly.
2. Security: Use a reverse proxy (Nginx/Traefik) for SSL termination. Do not expose port 8080 directly to the internet.
3. Scaling: This stateless service can be scaled horizontally, but ensure webhooks are distributed correctly and DB connections are pooled.

Known Gotchas

1. Circular Webhooks: Ensure you filter out updates caused by your own syncs to prevent infinite loops. Check sync_source in SyncMap before sending updates.
2. ADO Area Paths: Mapping is done via ado_area_path. Complex project structures require explicit mapping in ProjectMap.
3. ClickUp Task Descriptions: Long descriptions may be truncated. Ensure API limits are respected.
4. Rate Limiting: Both ADO and ClickUp have rate limits. Monitor SyncLog for 429 errors and implement backoff strategies if necessary.

Related

• 01 Projects/DevOps_Click_UP_sync/USER_MANUAL
• 01 Projects/DevOps_Click_UP_sync/USER_MANUAL.md
• 01 Projects/DevOps_Click_UP_sync/DEVELOPER_MANUAL.md