---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- domain/devops
- status/active
- tech/azure-ad
- tech/docker
- tech/fastapi
- tech/python
- tech/sqlite
- type/sop
type: 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
```bash
# 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
```bash
# 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]]