Edit Service Atlas — Service Atlas

Editing the page as plain markdown. The rich editor loads with the page; if it has not appeared, this field still saves normally.

# 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](https://github.com/CodexCoder21Organization/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.

Commit message

Cancel

Editing against commit 9467c5cbaeba3f3aece7df029ab93d65e0bce544. A save is refused if the atlas has moved past it, so a slow edit cannot discard somebody else's commit.