Documentation Edit this page

Service Atlas

The catalog you are reading. It answers three questions about every service on this platform: what it is, where to reach it, and whether what is written here still matches what is actually running.

The third is the one that makes it worth keeping. Documentation that nobody checks drifts away from reality quietly, and a catalog people have learned not to trust is worse than no catalog — it costs the same to read and returns a wrong answer. So the atlas measures itself against the deployment on every page load rather than asking anybody to keep it honest by hand.

Architecture

Browser ──HTTPS──► ServiceAtlasWui (service-atlas-wui.jar)
                     │
                     │ builds the catalog in-process
                     ▼
                   ServiceAtlasEmbedded
                     │
        ┌────────────┼─────────────────────┐
        │            │                     │
        ▼            ▼                     ▼
  url://githubproxy/  url://productionhealth/  ContainerNursery
  (manifests, pages,  (health verdicts)        (what is deployed)
   and edits)

The website builds the catalog inside its own process rather than calling url://service-atlas/. That route still exists for callers who want the catalog without the HTML, but the site does not use it: a separate service that stops when idle meant the first visitor to a cold site paid for a process launch and a full catalog read before any HTML could be written, and gave up before either finished.

Where the state lives

Nowhere here. Every fact on a page comes from a manifest committed to ServiceAtlas, and the only thing this service keeps is a cached snapshot of what it last read, so a restart does not re-read a hundred files. That cache is used only while its commit is still the branch head — and when the repository cannot be reached at all, the stored copy is served with a banner saying it may be out of date and naming the commit it came from, rather than the site serving nothing.

Editing

Every page here is editable in the browser: open a service and choose Edit. A save does not commit to the default branch — the repository's ruleset requires changes to arrive as a pull request, for this repository as for any other — so a save opens one and shows you its address. The page changes when that merges, not when you press save, and the page says so rather than leaving you to wonder whether your edit vanished.

An edit composed against an older commit is refused only when this page's own file changed underneath it. Somebody editing an unrelated page is not a conflict with yours.

What it will not tell you

The atlas reports what it can establish and says so plainly when it cannot, rather than defaulting to the reassuring answer:

• Drift is agreed, disagreed, or not comparable — never "fine" because the deployment could not be read.
• Health is passing, warning, failing, undetermined, or nothing is watching this. A check that crashed leaves the service undetermined rather than failing: whether the check ran and whether the thing it watches is healthy are different questions.
• Undeclared things — routes and health checks with no page — are listed per source, so a feeder that could not be consulted says so instead of contributing a reassuring silence.

There is no popularity score, no star rating and no service count that anybody typed in. Every figure on the site is counted from something real, which is the only reason to believe any of it.

Notes

• This page is itself a service page in the catalog, so it is subject to the same drift check as everything else — if these routes stop matching what is deployed, this page will say so about itself.
• No health check watches the atlas yet, so its own page reports that nothing is watching it. That is the honest state rather than an omission: a manifest can name a check, but naming one that is not registered would claim a watcher that does not exist.