Skip to content

Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.

refact: refactoring claude instructions and skills

karloks2005bba3b9846e11
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 040eaa5..151d0c0 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,69 +1,63 @@
# Project
-A self-hosted dashboard for monitoring all your homelab machines in one place. One machine runs the dashboard; every other machine runs a small collector that reports host and Docker container metrics back to it, and runs the uptime checks you define (HTTP, TCP, TLS, DNS, ping and more). It works the same whether the machines share a LAN or are spread across sites and VPSes.
-
-- Stack:
- - Backend: Python 3.12, FastAPI + Uvicorn, SQLAlchemy + Alembic on PostgreSQL 16 (psycopg), Redis (sessions, rate limits, agent job queue), bcrypt + cryptography/Fernet, openai (optional incident agent). Tests: pytest.
- - Frontend: React 19 + react-router-dom 7, Vite 8, Tailwind CSS v4, oxlint; built with Node 20, served by nginx. Tests: `node --test`.
- - Collectors: Python 3.12, standard library only (collector, docker-proxy, system-helper are single-file modules).
- - Infra: Docker Compose (dev `compose.yml`, server `docker-compose.server.yml`); nginx frontend + collector-gate; optional Traefik and Caddy; signed collector images on GHCR (cosign); CI on GitHub Actions.
-
-- Structure:
- - `src/backend/` — FastAPI app. `main.py` holds the app, middleware, startup, shared helpers and the baseline auth; HTTP routes live in `routes/` (account, admin, auth, availability, chat, incidents, monitoring, statistics). Domain/service modules alongside: `availability.py`, `incidents.py`, `alerts.py`, `rules.py`, `notify.py`, `dashboard.py`, `stats.py`, `history.py`, `rollups.py`, `retention.py`, `auth.py`, `totp.py`, `rate_limit.py`, `secrets_box.py`, `models.py`, `db.py`, `config.py`, `migrations/`.
- - `src/agent/` — optional incident agent: `providers.py`, `jobs.py`, `worker.py`, `diagnosis.py`, `chat.py`, `evidence.py`, `verify.py`, `safety.py`, `masking.py`, `usage.py`, `settings.py`, prompt `.md` files.
- - `src/collector/` — standalone, stdlib-only: `collector.py`, `docker_proxy.py`, `system_helper.py`.
- - `src/frontend/src/` — React, one folder per area: `dashboard/`, `availability/`, `agent/`, `statistics/`, `account/`, `admin/`, `auth/`, `more/`, plus shared `ui.jsx`/`api.js`/`shell.jsx`.
- - `docker/` (Dockerfiles, nginx, Caddyfile), `docs/`, `tests/` (mirror the backend areas), `floorplan/` (codebase map), `design/` (PDF mockups).
+infradeck: a self-hosted dashboard for monitoring homelab machines. One machine runs the dashboard; every other machine runs a small collector that reports host and Docker container metrics and runs user-defined uptime checks (HTTP, TCP, TLS, DNS, ping…). Works the same on a LAN or across sites and VPSes.
+
+## Stack
+- Backend: Python 3.12, FastAPI + Uvicorn, SQLAlchemy + Alembic, PostgreSQL 16 (psycopg), Redis (sessions, rate limits, agent job queue). Tests: pytest.
+- Frontend: React 19, react-router-dom 7, Vite 8, Tailwind CSS v4, oxlint, Node 20, served by nginx. Tests: `node --test`.
+- Collectors: Python 3.12, standard library only.
+- Infra: Docker Compose, nginx (frontend + collector-gate), optional Traefik/Caddy, signed collector images on GHCR (cosign), GitHub Actions CI.
+
+## Where things live
+- `src/backend/main.py`: app, middleware, startup, baseline auth. HTTP routes go in `src/backend/routes/`; domain logic in the modules next to it.
+- `src/agent/`: optional incident agent (LLM). Prompts are `.md` files there.
+- `src/collector/`: standalone single-file modules.
+- `src/frontend/src/`: one folder per area; shared code in `ui.jsx`, `api.js`, `shell.jsx`.
+- `tests/`: layout and conventions are documented in `TESTS.md`; read it before adding tests. `floorplan/` is the codebase map: check it before searching blindly.
+
+## Commands
+<!-- TODO: replace with the real commands -->
+- Dev stack: `docker compose up`
+- Backend tests: `pytest tests/`
+- Frontend tests + lint: `cd src/frontend && npm test && npx oxlint`
+- New migration: `alembic revision --autogenerate -m "<message>"` (review the generated file before applying)
# Workflow
-- For non-trivial changes, briefly outline the plan before writing code.
+- For non-trivial changes, outline the plan briefly before writing code.
- Change only what the task requires; don't refactor or reformat unrelated code.
-- Before saying a task is done, run tests, lint and typecheck and fix failures.
-- Code, comments and commit messages in English; reply to me in Croatian.
+- Before saying a task is done, run the tests and lint for the areas you touched and fix failures.
+- Code, comments, commit messages, issues and PR descriptions in English. Reply to me in Croatian.
# Ask before
-- Committing, pushing or creating branches
-- Running or writing database migrations
+- Committing, pushing, creating branches or opening PRs
+- Writing or running database migrations
- Deleting files or data
- Touching `.env*`, CI config, auth logic or deployment config
-- Adding any dependency (explain why it's needed, the alternatives, and why
- this one is best)
+- Adding any dependency: explain why it's needed, the alternatives (including a few lines of our own code), and why this one is best
+
+# Hard rules
+- `src/collector/` stays standard library only. Never add third-party packages there.
+- Never push directly to `main`, never force-push shared branches, never merge PRs.
+- Never close, reopen or relabel issues manually.
+- Anything sent to an LLM provider from `src/agent/` goes through `masking.py` first.
# Git & GitHub
-- One issue = one branch = one PR. Branch name: `<type>/<issue-number>-<short-desc>`
- (e.g. `fix/42-login-redirect`).
-- Commit messages: Conventional Commits (`feat:`, `fix:`, `refactor:`...).
-- Every PR description must reference its issue with `Fixes #<number>`
- so the issue closes automatically on merge.
-- Never close, reopen or relabel issues manually. Never merge PRs yourself.
-- If work only partially solves an issue, use `Refs #<number>` instead of
- `Fixes`, and list what's left in the PR description.
-- Before opening a PR: tests, lint and typecheck pass; summarize what
- changed and how it was verified.
-- Never force-push to shared branches or push directly to `main`.
-- Use english as default langauge for writing issues
+- One issue = one branch = one PR. Branch: `<type>/<issue-number>-<short-desc>` (e.g. `fix/42-login-redirect`).
+- Commits: Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:` …).
+- PR description: summary of changes, how it was verified, and `Fixes #<n>`. If the issue is only partly solved, use `Refs #<n>` and list what's left.
# Security
-- Validate and sanitize all external input (request body, params, headers, files).
-- Use parameterized queries / the ORM; never build SQL from strings.
-- Check authorization on every endpoint, not just authentication.
-- Never hardcode secrets; read them from environment variables.
+- Validate all external input (body, params, headers, files) with Pydantic models / explicit checks.
+- Use the ORM or parameterized queries; never build SQL from strings.
+- Check authorization on every endpoint, not just authentication. <!-- TODO: name the dependency/helper in main.py that does this -->
+- Secrets stored in the DB are encrypted via `secrets_box.py`; secrets from config come from environment variables, never hardcoded.
- Never log passwords, tokens or personal data.
-- Don't weaken security settings (e.g. CORS `*`, disabled TLS verification,
- disabled CSRF) to make something work.
-- Return generic error messages to clients; keep details in server logs.
-- If unsure about a security decision, stop, ask, and explain the trade-offs.
-
-# Code organization
-- One file, one responsibility; if a file exceeds ~300 lines, suggest a split.
-- Keep functions short and single-purpose.
-- Follow the existing folder structure and naming conventions.
-- Put new files where a person would naturally look for them.
-
-## Simplicity
-- Always choose the simplest solution that correctly solves the problem.
-- Don't add abstractions, configuration or features that weren't asked for, in case you think adding abstraction is a better approach propose it to the user and explain why is it better.
-- Don't add new dependencies if the problem can be solved with existing ones
- or a few lines of code; if a dependency is necessary, ask first and provide argumented explanation.
-- Less code means a smaller attack surface: avoid unnecessary code, exposed
- endpoints, overly broad permissions and complex logic.
-- Simpler solution is the default, propose the complex one with explanation
\ No newline at end of file
+- Don't weaken security settings (CORS `*`, disabled TLS verification, disabled CSRF) to make something work.
+- Return generic errors to clients; keep details in server logs.
+- If unsure about a security decision, stop and explain the trade-offs.
+
+# Code style
+- Choose the simplest solution that correctly solves the problem. Less code = smaller attack surface.
+- Don't add abstractions, config or features nobody asked for. If you think a more complex approach is better, propose it and explain why. Don't just do it.
+- Keep functions short and single-purpose; one file, one responsibility.
+- If a file you create or substantially change goes past ~300 lines, suggest a split.
+- Follow the existing structure and naming; put new files where a person would look for them.
\ No newline at end of file
diff --git a/.claude/skills/simplify-existing-code.md/simplify-existing-code.md b/.claude/skills/simplify-existing-code.md/simplify-existing-code.md
index 1e495cb..115fe85 100644
--- a/.claude/skills/simplify-existing-code.md/simplify-existing-code.md
+++ b/.claude/skills/simplify-existing-code.md/simplify-existing-code.md
@@ -1,26 +1,42 @@
---
name: simplify-existing-code
-description: Koristi kad treba pojednostaviti postojeći kod koji je prekomplikiran: ukloniti nepotrebne apstrakcije, slojeve, nekorištene parametre ili mrtvi kod, a da se ponašanje ne promijeni. Ne koristi za pisanje novog koda (code-simplicity) ni za male ciljane popravke (minimal-diff).
+description: Use when asked to simplify, clean up or de-bloat existing code that is overcomplicated — unnecessary abstractions, layers, wrappers, unused parameters, dead code — without changing its behavior. Not for writing new code or for small targeted fixes (minimal-diff).
---
-# Pojednostavljenje postojećeg koda
-
-Cilj je manje koda uz isto ponašanje. Prije nego što išta mijenjaš, moraš razumjeti što kod radi.
-
-## Postupak
-
-1. **Utvrdi ponašanje.** Pročitaj kod i kratko opiši što radi, uključujući rubne slučajeve. Ako postoje testovi, pokreni ih prije izmjena i zabilježi rezultat.
-2. **Traži kandidate za uklanjanje:** apstraktne klase s jednom implementacijom, wrapper funkcije koje samo prosljeđuju poziv, parametri koji se uvijek dobivaju istu vrijednost, grane koje se nikad ne izvršavaju, nekorištene funkcije (provjeri pretragom po projektu prije brisanja).
-3. **Mijenjaj u malim koracima.** Jedna vrsta pojednostavljenja po koraku, nakon čega provjeri testove ili ponašanje.
-4. **Ne diraj javna sučelja** koja koriste drugi dijelovi sustava, osim ako je to dio dogovorenog zadatka.
-5. **Sačuvaj prijašnje ponašanje u iznimkama i rubnim slučajevima.** Pojednostavljenje ne smije tiho promijeniti poruke grešaka, redoslijed obrade ili tipove povratnih vrijednosti.
-
-## Što ne raditi
-
-- Ne prepisuj kod u "savršeniji" obrazac ako to nije potrebno za smanjenje složenosti.
-- Ne uklanjaj obradu grešaka za ulaze izvana, čak i ako izgleda suvišno.
-- Ne mijenjaj ponašanje kako bi kod bio kraći.
-
-## Izvještaj
-
-Na kraju ukratko navedi: što si uklonio ili pojednostavio, je li ponašanje ostalo isto (i kako si to provjerio) te što si primijetio, ali nisi dirao.
\ No newline at end of file
+# Simplify existing code
+
+Goal: less code, same behavior. Understand what the code does before changing anything.
+
+## Scope
+- One module or area per run. If the request is broader, propose an order and start with the first.
+- Splitting a file that is too long is a separate step. Don't mix it with simplification in the same diff.
+
+## Process
+
+1. **Pin down current behavior.** Read the code and summarize what it does, including edge cases and error paths. Run the existing tests and lint for that area and record the result.
+ - If the code has no tests, say so and offer to first write tests that capture current behavior (placement per `TESTS.md`). Don't simplify untested code without my OK.
+2. **Find candidates.** Typical bloat:
+ - Backend: abstract classes or interfaces with one implementation; wrappers that only forward a call; parameters that always receive the same value; config nobody sets; branches that can't run; duplicated logic; exceptions that are swallowed (`except: pass`) or caught only to be re-raised; unused functions, imports and models.
+ - Frontend: `useEffect` or state for values that can be derived; components that only wrap a single element; unused props, hooks and helpers.
+3. **Propose before editing.** List each candidate with: what it is, why it's safe to remove or simplify, and risk (low/medium/high). Wait for my approval before changing code.
+4. **Change in small steps.** One kind of simplification per step; run tests and lint after each step.
+5. **Report** (see below).
+
+## Before removing anything "unused"
+A search with no hits is not proof. Also check:
+- dynamic references: string routes in `src/frontend/src/api.js`, `getattr`, FastAPI dependencies, Alembic migrations, agent prompt `.md` files;
+- callers outside this repo's runtime: collectors on other machines may run older versions.
+Deleting whole files requires asking first (see CLAUDE.md).
+
+## Don't change
+- **Interfaces other parts depend on**: HTTP endpoints and payloads used by the frontend or collectors, the database schema (needs a migration, so ask first), the collector ↔ backend protocol.
+- **Behavior at the edges**: error messages, status codes, processing order, return types.
+- **Security code, even if it looks redundant**: authorization checks, input validation, rate limiting, `masking.py`, `secrets_box.py`. If you think one is truly redundant, flag it and explain; don't remove it.
+- **The collector's stdlib-only rule**: never "simplify" by adding a third-party package.
+- Don't rewrite code into a "nicer" pattern unless it actually reduces complexity.
+
+## Report
+At the end, briefly state:
+- what was removed or simplified, and lines before → after;
+- how unchanged behavior was verified (which tests and lint ran);
+- what you noticed but didn't touch, and why.
\ No newline at end of file