obsidian/01 Projects/DevOps_Click_UP_sync/DevOps ClickUp Sync.md

name	client	status	tech	local_path	deploy	url	tags	created	server	port	db
DevOps ↔ ClickUp Sync	Oliver	active	Python FastAPI SQLAlchemy SQLite Docker Azure DevOps API ClickUp API	/Users/ai_leed/Documents/Projects/Oliver/DevOps_Click_UP_sync	docker-compose up	http://localhost:8080	oliver devops ado clickup sync webhook	2026-04-14	local	8080	SQLite

Overview

DevOps_Click_UP_sync is a bidirectional synchronization service that bridges Azure DevOps and ClickUp, enabling seamless task/work item management across both platforms. It runs as a containerized FastAPI application that listens for webhooks and maintains data consistency between the two systems. The service is designed for teams using both Azure DevOps and ClickUp who need unified task tracking without manual duplication.

Tech Stack

• Frontend: N/A (API-only service)
• Backend: Python 3.x, FastAPI, Uvicorn ASGI server
• Database: SQLite with SQLAlchemy ORM and async support (aiosqlite)
• Infrastructure: Docker, Docker Compose
• AI/ML: N/A
• Key libraries: FastAPI, SQLAlchemy, httpx (async HTTP client), Pydantic (validation), markdownify (content conversion)

Architecture

The service follows a webhook-based event-driven architecture:

┌─────────────────────────────────────────────────────┐
│         External Systems                            │
│  ┌──────────────────┐      ┌──────────────────┐    │
│  │  Azure DevOps    │      │    ClickUp       │    │
│  └────────┬─────────┘      └────────┬─────────┘    │
└───────────┼────────────────────────┼───────────────┘
            │ Webhooks               │ Webhooks
            └────────────┬───────────┘
                         │
        ┌────────────────▼─────────────────┐
        │  FastAPI Sync Service            │
        │  ┌──────────────────────────┐    │
        │  │ /api/health              │    │
        │  │ /api/webhook/ado         │    │
        │  │ /api/webhook/clickup     │    │
        │  │ /api/sync                │    │
        │  └──────────────────────────┘    │
        └────────────────┬──────────────────┘
                         │
        ┌────────────────▼─────────────────┐
        │  SQLite Database (/app/data)     │
        │  - Sync mappings                 │
        │  - Metadata                      │
        └──────────────────────────────────┘

Key Design Decisions:

• Async-first: All database and HTTP operations use async/await for scalability
• Webhook-driven: Listens for changes from both platforms rather than polling
• Content conversion: Uses markdownify to normalize formatting between systems
• Health checks: Built-in health endpoint for container orchestration
• Persistent storage: SQLite for tracking sync state and mappings

Dev Commands

# Install dependencies
pip install -r requirements.txt

# Create .env file from template
cp .env.example .env
# Edit .env with your credentials

# Run locally (requires Python 3.9+)
python -m uvicorn main:app --reload --port 8080

# Build and run with Docker
docker-compose up --build

# View logs
docker-compose logs -f sync-service

# Stop services
docker-compose down

# Access health check
curl http://localhost:8080/api/health

Deployment

• Server: local (intended for container deployment)
• Deploy: docker-compose up -d
• URL: Configured via PUBLIC_URL env var (e.g., https://your-domain.com)
• Port: 8080
• Service: Docker container managed by docker-compose
• Local path: /Users/ai_leed/Documents/Projects/Oliver/DevOps_Click_UP_sync

Container details:

• Health check runs every 30s (timeout 10s, 3 retries)
• Auto-restart policy: unless-stopped
• Volumes: ./data mounted to /app/data (persistent database storage)

Environment Variables

• ADO_ORGANIZATION — Azure DevOps organization name
• ADO_PROJECT — Azure DevOps project name
• ADO_PAT — Azure DevOps Personal Access Token (authentication)
• CLICKUP_API_TOKEN — ClickUp API token (format: pk_*)
• CLICKUP_WORKSPACE_ID — ClickUp workspace identifier
• WEBHOOK_SECRET — Secret key for validating incoming webhooks
• PUBLIC_URL — Public domain/URL where this service is accessible (for webhook callbacks)
• LOG_LEVEL — Logging verbosity (INFO, DEBUG, etc.)
• DATABASE_URL — SQLite connection string; default: sqlite+aiosqlite:///./data/sync.db

API / Endpoints

• GET /api/health — Health check endpoint (used by Docker healthcheck)
• POST /api/webhook/ado — Receives webhook events from Azure DevOps
• POST /api/webhook/clickup — Receives webhook events from ClickUp
• POST /api/sync — Manually trigger synchronization (if implemented)

Known Issues

None documented. Ensure webhook payloads are validated with WEBHOOK_SECRET to prevent unauthorized sync triggers.

Git

• Remote: [Not provided in source files]

Sessions

2026-04-14 – Project catalogued

Done: Added to Obsidian second brain.

---

Change Log

Date	Requested	Changed	Files
2026-04-14	Initial setup	Note created	—