# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Local dev
pip install -r requirements.txt
cp .env.example .env   # fill in credentials
uvicorn app.main:app --reload

# Docker
docker compose up --build

# No test suite or linter configured yet
```

## Architecture

FastAPI webhook service bridging **Zammad** (support ticketing) and **Azure DevOps** (work tracking).

**Flow when a Zammad ticket is created:**
1. POST `/webhook/ticket-created` — verifies HMAC-SHA1 signature (`X-Hub-Signature`), enqueues background task
2. `_process_ticket` (background) → fetches full ticket from Zammad API
3. `devops.ensure_and_create` — idempotently gets/creates the current-month iteration (`M_MAY_2026`), gets/creates a monthly "Maintenance :: May 2026" User Story, then creates a Task child linked to that story
4. `zammad.post_comment` — posts HTML comment back to Zammad ticket with DevOps task ID and link

**Module responsibilities:**
- `app/config.py` — pydantic-settings; all config comes from `.env` / environment variables
- `app/zammad.py` — Zammad REST API calls (get ticket, post article/comment); auth via `Token token=…`
- `app/devops.py` — Azure DevOps REST API (classification nodes, WIQL queries, work item creation); auth via Basic PAT; uses `api-version=7.1`
- `app/main.py` — FastAPI app wiring, signature verification, webhook and health endpoints

**Iteration naming convention:** `M_{MONTH}_{YEAR}` (e.g. `M_MAY_2026`). Story title: `Maintenance :: May 2026`. Both are month-scoped and auto-created if missing.

**Signature verification:** disabled when `WEBHOOK_SECRET` is empty (useful for local testing).

## Config reference

| Var | Purpose |
|-----|---------|
| `ZAMMAD_URL` | Base URL of Zammad instance |
| `ZAMMAD_TOKEN` | Zammad API token |
| `DEVOPS_ORG` | Azure DevOps org name |
| `DEVOPS_PROJECT` | Project name (used in iteration paths and URLs) |
| `DEVOPS_TEAM` | Team name (for assigning iterations to the team) |
| `DEVOPS_PAT` | Personal access token |
| `WEBHOOK_SECRET` | Optional HMAC secret; leave blank to skip verification |
| `FIRST_COMMENT` | Text prepended to the Zammad comment (has default) |