Salus/CLAUDE.md

CLAUDE.md

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

Development Commands

# Local setup
python -m venv .venv
source .venv/Scripts/activate          # Windows Git Bash
pip install -r requirements.txt
cp .env.example .env                   # fill in values

# Run locally (pick any free port; earlier dev sessions may occupy 8080–8094)
uvicorn app.main:app --reload --port 8080

# Skip Authentik login entirely during local dev
AUTH_DISABLED=true uvicorn app.main:app --reload --port 8080

# Docker
docker build -t qwe-salus:latest .
docker compose up

There are no tests and no linter configured.

Architecture

Request flow

Browser → FastAPI (main.py)
            ├── auth.py        – Authentik OIDC + session management
            ├── omada.py       – Omada Controller API client (singleton)
            └── database.py    – SQLAlchemy / SQLite audit log

Templates extend base.html (nav, footer, toast system). TailwindCSS is loaded from CDN — no build step.

Critical: module-level os.getenv() ordering

app/main.py calls load_dotenv() before any from app.* imports. omada.py and auth.py read their config via os.getenv() at module load time, so .env must be loaded first. Moving load_dotenv() below those imports silently breaks all env var config.

OmadaClient (app/omada.py)

A module-level singleton (omada_client). Key behaviour:

• Two separate httpx.AsyncClient instances: _get_client() carries the web session cookie (TPOMADA_SESSIONID); _get_openapi_client() is cookie-free. Mixing them causes 401s on the OpenAPI token endpoint.
• Auth flow: _fetch_omadac_id() → _login() (username/password → CSRF token + session cookie) → _fetch_sites(). _ensure_ready() gates all public methods.
• Sites are fetched from GET /api/v2/users/current → result.privilege.sites[], not /api/v2/sites (which requires root admin and returns empty for regular admins).
• Devices list: GET /{omadacId}/api/v2/sites/{siteKey}/devices filtered by type == "ap". There is no /aps endpoint in v6.x.
• Reboot: POST /{omadacId}/api/v2/sites/{siteKey}/cmd/devices/{mac}/reboot via the web session client. Response errorCode: -39009 with "Rebooting... Please wait." is the success response — treat it as non-error alongside 0. OpenAPI client credentials (OMADA_CLIENT_ID/OMADA_CLIENT_SECRET) are no longer used for reboot.
• Session expiry is handled in _request_with_retry: error codes -1006, -1003, -30109 trigger automatic re-login + re-fetch of sites. If all sites fail in get_aps(), the token and sites cache are cleared so the next request triggers a fresh login rather than staying broken indefinitely.
• Uptime safety check: reboot_ap() re-fetches live uptime before issuing the command; it raises if uptimeLong < 300 seconds (5 minutes). The UI also disables the reboot button client-side for the same condition.
• Connected clients: get_ap_clients(ap_mac, site_key) fetches clients for a specific AP via GET /sites/{key}/clients?filters.apMac={mac}, with automatic fallback to fetching all site clients and filtering client-side if the controller doesn't support that query param. get_all_clients() fetches all clients across all sites grouped by AP MAC.

API endpoints (app/main.py)

Beyond the page routes, the JSON API endpoints are:

Method	Path	Purpose
POST	/api/reboot	Reboot a single AP; CSRF-validated
POST	/api/reboot-bulk	Reboot multiple APs; CSRF-validated
GET	/api/ap-clients	?mac=&site_key= — clients connected to one AP
GET	/api/all-clients	All clients across all sites, keyed by AP MAC
GET	/health	Docker healthcheck
GET	/debug/sites	Lists accessible Omada sites (diagnostic)

Authentication (app/auth.py)

Authentik OIDC Authorization Code Flow. The JWT id_token is decoded without signature verification (Authentik is a trusted internal IdP). User dict {username, email, name, sub} is stored in the Starlette signed-cookie session.

AUTH_DISABLED=true injects a hardcoded DEV_USER on /auth/login — no Authentik required.

All POST API endpoints validate a CSRF token stored in the session and echoed in the JSON request body.

Database (app/database.py)

Single table reboot_log written on every reboot attempt (success and error). DB_PATH defaults to /data/audit.db (Docker volume mount). Override to ./audit.db for local dev.

Frontend (app/templates/index.html)

Key client-side behaviours to be aware of when editing:

• Reboot locking: lockApRow(mac) disables the row button and checkbox immediately on confirm — button text transitions Rebooting… → Rebooted / Failed and stays disabled for the session.
• Clients popup: clicking an AP name cell fires openClientsModal(), which calls /api/ap-clients and renders a modal table sorted by IP. Uses the same ipToNum() helper as the column sort.
• IP range filter ("Filter .150–.155"): fetches /api/ap-clients for every AP in parallel via Promise.all, retains only APs where a connected client IP has last octet 150–155. Result is cached in ipMatchedMacs (a Set) for the session.
• Column sort: Name, Site, IP Address headers are clickable. ipToNum() is used for numeric IP comparison. Default sort on load is by Name (triggered by programmatic .click() on the Name header). Both the text filter and the IP range filter compose with the sort via a shared applyFilters() function.

Deployment

• Docker exposes port 8080; docker-compose.yml maps it to host port 8098.
• Uvicorn runs with --proxy-headers --forwarded-allow-ips=* to trust X-Forwarded-Proto from Nginx Proxy Manager.
• The /health endpoint is used by the Docker healthcheck.
• /debug/sites is a diagnostic endpoint that lists all accessible Omada sites — useful for verifying credentials without touching the UI.