From 963c42246b3ddd7d22736561af66825544e85f45 Mon Sep 17 00:00:00 2001
From: codex <codex@bstein.dev>
Date: Fri, 19 Jun 2026 15:46:34 -0300
Subject: [PATCH] docs: add concise ariadne README

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a84bb92
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# ariadne
+
+Ariadne is the Atlas admin and account automation service.
+
+It sits behind the portal and handles the jobs that are annoying or risky to do
+by hand: approving access, syncing account state, rotating service passwords,
+cleaning stale Kubernetes work, checking platform health, and keeping a few
+service integrations lined up.
+
+## How it works
+
+Ariadne is a FastAPI service with a small scheduler. It talks to Keycloak,
+Vault, Mailu, Nextcloud, Wger, Firefly, Jenkins, Metis, Kubernetes, and a few
+Atlas-specific services through focused adapters under `ariadne/services/`.
+
+The API is split between admin routes, account self-service routes, internal
+event hooks, and Prometheus metrics. Background jobs store run history in the
+Ariadne database so failures can be inspected later instead of vanishing into
+logs.
+
+Useful routes:
+
+- `GET /health`
+- `GET /metrics`
+- `GET /api/admin/cluster/state`
+- `POST /api/admin/access/requests/{username}/approve`
+- `POST /api/account/mailu/rotate`
+- `POST /api/account/wger/reset`
+- `POST /api/account/firefly/reset`
+- `POST /events`
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+```
+
+Most runtime behavior is configured through environment variables in
+`ariadne/settings.py`. Keep service-specific logic in the small adapter modules;
+`ariadne/app.py` should stay focused on request flow and task orchestration.