# Mosaic Coordinator

FastAPI webhook receiver for Gitea issue events, enabling autonomous task coordination for AI agents.

## Overview

The coordinator receives webhook events from Gitea when issues are assigned, unassigned, or closed. It verifies webhook authenticity via HMAC SHA256 signature and routes events to appropriate handlers.

## Features

- HMAC SHA256 signature verification
- Event routing (assigned, unassigned, closed)
- AI-powered issue metadata parsing (using Anthropic Sonnet)
- Context estimation and agent assignment
- Dependency tracking (blocks/blocked_by)
- Comprehensive logging
- Health check endpoint
- Docker containerized
- 95%+ test coverage

## Development

### Prerequisites

- Python 3.11+
- pip or uv package manager

### Setup

```bash
# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Type checking
mypy src/

# Linting
ruff check src/
```

### Running locally

```bash
# Copy environment template
cp .env.example .env

# Edit .env with your values
# GITEA_WEBHOOK_SECRET, GITEA_URL, ANTHROPIC_API_KEY

# Run server
uvicorn src.main:app --reload --port 8000
```

## API Endpoints

### POST /webhook/gitea

Receives Gitea webhook events.

**Headers:**

- `X-Gitea-Signature`: HMAC SHA256 signature of request body

**Response:**

- `200 OK`: Event processed successfully
- `401 Unauthorized`: Invalid or missing signature
- `422 Unprocessable Entity`: Invalid payload

### GET /health

Health check endpoint.

**Response:**

- `200 OK`: Service is healthy

## Environment Variables

| Variable               | Description                                 | Required | Default |
| ---------------------- | ------------------------------------------- | -------- | ------- |
| `GITEA_WEBHOOK_SECRET` | Secret for HMAC signature verification      | Yes      | -       |
| `GITEA_URL`            | Gitea instance URL                          | Yes      | -       |
| `ANTHROPIC_API_KEY`    | Anthropic API key for issue parsing         | Yes      | -       |
| `LOG_LEVEL`            | Logging level (debug, info, warning, error) | No       | info    |
| `HOST`                 | Server host                                 | No       | 0.0.0.0 |
| `PORT`                 | Server port                                 | No       | 8000    |

## Docker

```bash
# Build
docker build -t mosaic-coordinator .

# Run
docker run -p 8000:8000 \
  -e GITEA_WEBHOOK_SECRET="your-secret" \
  -e GITEA_URL="https://git.mosaicstack.dev" \
  -e ANTHROPIC_API_KEY="your-anthropic-key" \
  mosaic-coordinator
```

## Testing

```bash
# Run all tests
pytest

# Run with coverage (requires 85%+)
pytest --cov=src --cov-report=term-missing

# Run specific test file
pytest tests/test_security.py

# Run with verbose output
pytest -v
```

## Architecture

```
apps/coordinator/
├── src/
│   ├── main.py             # FastAPI application
│   ├── webhook.py          # Webhook endpoint handlers
│   ├── parser.py           # Issue metadata parser (Anthropic)
│   ├── models.py           # Data models
│   ├── security.py         # HMAC signature verification
│   ├── config.py           # Configuration management
│   └── context_monitor.py  # Context usage monitoring
├── tests/
│   ├── test_security.py
│   ├── test_webhook.py
│   ├── test_parser.py
│   ├── test_context_monitor.py
│   └── conftest.py         # Pytest fixtures
├── pyproject.toml          # Project metadata & dependencies
├── .env.example            # Environment variable template
├── Dockerfile
└── README.md
```

## Related Issues

- #156 - Create coordinator bot user
- #157 - Set up webhook receiver endpoint
- #158 - Implement issue parser
- #140 - Coordinator architecture