133 lines
No EOL
5.9 KiB
Markdown
133 lines
No EOL
5.9 KiB
Markdown
---
|
||
name: "DevOps ↔ ClickUp Sync"
|
||
client: Oliver
|
||
status: active
|
||
tech: [Python, FastAPI, SQLAlchemy, SQLite, Docker, Azure DevOps API, ClickUp API]
|
||
local_path: /Users/ai_leed/Documents/Projects/Oliver/DevOps_Click_UP_sync
|
||
deploy: docker-compose up
|
||
url: http://localhost:8080
|
||
tags: [oliver, devops, ado, clickup, sync, webhook]
|
||
created: 2026-04-14
|
||
server: local
|
||
port: 8080
|
||
db: 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
|
||
```bash
|
||
# 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 | — | |