# CLAUDE.md

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

## Project Overview

This is a Home Assistant add-on that provides an NTP server and client using Chrony. It includes a Flask-based web UI for monitoring synchronization status.

## Development Environment

Use the devcontainer configuration for local development. The devcontainer uses the Home Assistant add-on development image and mounts the workspace at `/mnt/supervisor/addons/local/`.

To start Home Assistant with the add-on for testing:
```bash
supervisor_run
```

Ports exposed in devcontainer:
- 7123 → 8123 (Home Assistant)
- 7357 → 4357 (debug)

## Architecture

**Container Runtime**: Alpine-based image using s6-overlay for process supervision.

**Services (s6-rc.d)**:
- `chrony`: Main NTP daemon - reads `/data/options.json`, generates `/etc/chrony/chrony.conf`, runs `chronyd -d`
- `webui`: Flask app on port 8099 (or INGRESS_PORT env var) - provides status dashboard and API

**Configuration Flow**: Home Assistant writes add-on config to `/data/options.json` → `chrony/run` script parses with `jq` → generates chrony.conf → starts chronyd

**Web UI** (`rootfs/var/www/`):
- `app.py`: Flask app with routes for dashboard and API endpoints (`/api/status`, `/api/options`, `/api/force-sync`, `/api/burst`)
- Uses `chronyc -c` commands to get machine-readable status output
- Templates use Jinja2 with Home Assistant-style dark theme

## Key Files

- `config.yaml`: Add-on metadata, schema, ports, privileges (SYS_TIME required for time sync)
- `build.yaml`: Architecture-specific base images
- `Dockerfile`: Installs chrony, jq, python3, py3-flask
- `rootfs/etc/s6-overlay/s6-rc.d/*/run`: Service startup scripts

## Add-on Configuration Schema

Options defined in `config.yaml`:
- `ntp_servers`: List of `{server: str, iburst: bool?}`
- `allow_clients`: List of CIDR networks
- `enable_ntp_server`: bool
- `log_level`: debug|info|warning|error