← Workstreams

Workstream: ServiceAtlas

Status: In progress · Component: Maximize developer productivity

Goal

The central hub for all services. ServiceAtlas is the place you go to find a service that might meet your needs, read its documentation, jump to its WUI (when one exists), and see how it is deployed. It replaces HostedServiceDocumentation — a hand-maintained pile of markdown browsed through GitHub — with a real service: a browsable, searchable catalog backed by structured documentation, with an in-browser editor so maintainers keep their service pages current instead of letting them rot.

The atlas serves both audiences of the plan. For a human, it answers "what service does X, and where do I click?" For an agent, it is the service registry of the swarm: a programmatic answer to "what services exist, what do they do, and where do I call them?" — the discovery step that precedes every openSandboxedConnection an agent makes.

Current state

  • ServiceAtlas — the renamed and restructured documentation repository — now holds 47 services as services/<slug>/manifest.json + page.md and six platform pages under platform/<slug>/, with the catalog table in the README generated from the manifests and continuous integration rejecting a manifest that fails its schema or a catalog that has drifted. Its predecessor, HostedServiceDocumentation, held the same material as freeform markdown with a hand-maintained index, and had the classic documentation failure mode: routes, JARs, and deployment details drifted from what ContainerNursery actually runs, and nothing surfaced the drift.
  • The service is deployed. ServiceAtlasApi, ServiceAtlasEmbedded, ServiceAtlasServiceServer, and ServiceAtlasWui are all built and merged; the catalog is browsable at services.wasmserver.com, whose domain and TLS certificate are live, and the ServiceServer serves the same catalog over url://service-atlas/.
  • The pieces the atlas composes already exist: ContainerNursery exposes its routes and containers over an API, ProductionHealth knows which services are healthy, SearchableBucket provides full-text search, GithubProxy provides typed git operations, and ExternalBrainWui ships the rich hybrid markdown editor (deployed at my.externalbrain.wasmserver.com) that the atlas's editor experience is modeled on.

The shape

The decisions below are settled.

Full replacement of the old hosted-service documentation. The atlas subsumes the whole repository: per-service pages, and the platform-level infrastructure/ and operations/ content, which migrate in as a second page type (platform pages — same shape, slimmer manifest). The "three complementary documentation repositories" trio becomes DocumentationRepository (what exists and how repositories fit together), PlanRepository (where we are headed), and ServiceAtlas (what is deployed and running, and how to use it).

The documentation is a git repository, renamed in place. HostedServiceDocumentation was renamed to ServiceAtlas and restructured in place — GitHub redirects old links, and every existing document's revision history carried over seamlessly. Git remains the system of record: every edit, human or via the editor, is a commit, so revision history is maintained for all documentation forever, and bulk/structural changes remain ordinary PRs made directly against the repo.

Mostly structured: a manifest plus a page. Each service is a directory — services/<slug>/manifest.json + services/<slug>/page.md:

  • manifest.json carries everything machine-readable: display name, one-line description, category, status, WUI link(s), HTTPS routes and url:// endpoints (with JAR and provider), repositories typed by standard-architecture layer, dependencies and dependents as url:// references, health checks, declared deployment configuration, and an informational maintainers list. This is what the catalog, search, and agents consume.
  • page.md carries the prose: architecture, operational notes, gotchas — what the editor edits.

Platform pages follow the same shape under their own directory. The repository README's catalog table is generated from the manifests on commit, so browsing the repo on GitHub stays pleasant with no hand-maintained index.

One service in the standard layered architecture. ServiceAtlasApi / ServiceAtlasEmbedded / ServiceAtlasServiceServer / ServiceAtlasWui, served over url://service-atlas/ with the WUI at services.wasmserver.com, where each service has a page at /services/<slug>. The ServiceServer reads and writes the git repository (via GithubProxy's typed git operations); the WUI is a stateless frontend.

Deployment info is declared and live, with drift flagged. The manifest's deployment section is the declared configuration — versioned, reviewed, revertible. The atlas overlays the actual state queried live from ContainerNursery (routes, JARs) and ProductionHealth (health badges on every catalog entry and page), and prominently flags any documented-vs-actual mismatch. Stale documentation stops being silently wrong and becomes a visible defect on the page itself.

Editing is wiki-style. A save in the editor becomes one direct commit to main — no PR ceremony for routine page upkeep, because these are docs whose safety nets are revision history and the drift flag. Saves carry the base commit SHA they were loaded from and are rejected on mismatch, so concurrent edits never silently clobber each other. The editor itself is the hybrid markdown editor extracted from ExternalBrainWui into a shared, reusable component consumed by both WUIs (the External Brain rebuild benefits from the same extraction); manifests are edited through structured form fields alongside it.

Open editing now, wallet capabilities later — a deliberate deferral. For v1 there is no authentication: everyone can edit every service, and edits are attributed to the atlas service identity. Eventually each service will have associated W3Wallet capabilities gating who may edit its page; that lands as its own milestone once the wallet's secure-my-service path is the ecosystem norm, and the manifest's maintainers field is the natural seed for those grants.

Three discovery surfaces over the same manifests. (1) Browse — the catalog grouped by category (seeded from today's README sections), each entry with its one-liner, WUI link, and live health badge. (2) Search — pages and manifests indexed into SearchableBucket, re-indexed on each commit, so "which service stores blobs?" finds answers in prose, not just titles. (3) Programmatic — url://service-atlas/ exposes list/search/get-manifest, making the atlas the swarm's service registry. RAG-style "chat with the catalog" is out of scope; that direction belongs to the External Brain's chat.

Plan / roadmap

Milestones in proposed order; each earns its own detailed design in its implementation repository as it starts — this plan owns the shape, not the internals.

  • [x] Schema and restructuring. Define the manifest schema; rename HostedServiceDocumentation to ServiceAtlas; restructure all per-service documents into services/<slug>/manifest.json + page.md and the platform docs into platform pages; generate the catalog README from the manifests. Shipped: 47 services and six platform pages, with continuous integration validating every manifest and the generated catalog.
  • [x] Atlas contract and service. The Api over url://service-atlas/ — catalog listing, page retrieval, manifest queries — with the Embedded/ServiceServer reading the git repository through GithubProxy. Shipped as ServiceAtlasApi + ServiceAtlasEmbedded, then ServiceAtlasServiceServer deployed on ContainerNursery.
  • [x] Catalog WUI. Browse by category with one-liners, WUI links, and live ProductionHealth badges; service pages rendering page.md plus the manifest, with the live ContainerNursery overlay and the documented-vs-actual drift flag. Shipped as ServiceAtlasWui, live at services.wasmserver.com over its own TLS certificate.
  • [ ] Shared editor and edit mode. In progress. Extract the hybrid markdown editor from ExternalBrainWui into a reusable component; atlas edit mode with form-based manifest editing, direct commits to main, and base-SHA stale-save protection.
  • [ ] Search. In progress. Index manifests and pages into SearchableBucket on each commit; search in the WUI and over url://service-atlas/.
  • [ ] Cross-reference cutover. In progress. Update the references to the old HostedServiceDocumentation repository across the DocumentationRepository, this repository, and the agent instruction files to point at ServiceAtlas and services.wasmserver.com as the operational system of record.
  • [ ] Per-service edit capabilities. The deferred W3Wallet integration: each service's page gated by its own edit capability, granted per the manifest's maintainers, with editor attribution riding the wallet identity.

Graduation

This remains a workstream until a user can find a service by browsing or searching the atlas, read its page with live deployment/health information, follow the link to its WUI, and edit its documentation in the browser — with the renamed ServiceAtlas repository serving as the system of record behind url://service-atlas/. Browsing and live deployment information are in place at services.wasmserver.com; searching and in-browser editing are what remain. At that point the Documentation Repository gains a ServiceAtlas project page, and this document has done its job.