stack/apps/coordinator

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

# 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

# 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

# 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

# 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