App flow — package and project navigation
How a reader moves around a package or project: its tracks, version lines and the moves between them, screen by screen.
Snapshot of the system as it stands today. Edit in place; never record what changed.
What a person sees and how they move through it. Sample values are invented (ADR-0008). Phone width first; desktop differences are noted under each screen.
Every package and project has the same shape (ADR-0013, ADR-0015). Its overview is at
/<slug>, under the package hero, and it has two tracks: Use, for people using it, and
Maintain, for people who look after it. A package's Use track has one line per documented
release, at the URL segment of the name its meta.json gives (v0.1, 2024-lts), plus dev
for the work in progress. The sidebar shows the current track and line only. At its top sit
the version menu (on Use pages of a versioned package) and, under it, the package name with the
Use | Maintain switch. The site header, its search and the theme switch are described in
site pages.
The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in diagrams/docs/: package-navigation.json for the
flow, one package-navigation-screen-<n>.json per screen.
Entry points
- A row in the home page catalogue, or a search result.
- A README or registry badge linking to
/<slug>or to a stable alias such as/lodestar/use/latest/install, which redirects to the line markedlatest(ordevbefore the first release)./lodestar/useopens the first page of that line. - A direct URL to a line:
/lodestar/use/v0.1/install,/lodestar/use/dev/install. A line that does not exist (removed, or never there) redirects to the same path inlatest. - The Markdown version of any page:
/lodestar/use/v0.1/install.md. - Everyone sees every public package and project. Private projects have no pages here until the private-documentation ADR is approved; when it is, a signed-out visitor at a private URL gets the same 404 as for a page that does not exist, so the URL does not confirm the project exists.
Flow
Screens
1. Overview — /<slug>
The package hero, then the package's own index.mdx, as its repository writes it. The sidebar
is the latest Use line's, as on screen 2, with Overview first and current; an entry without
Use shows Maintain's (ADR-0025, drawn in the overview's sidebar). The
hero is drawn in site pages.
Desktop: the same, with the sidebar always visible.
States
- Empty: a package with one track shows no switch, only its name.
- Loading: none; prerendered.
- Not found: an unknown slug shows the site's 404.
- Refused: not applicable until private documentation exists (see Entry points).
- Error: a malformed catalogue field fails the build, so it never reaches readers.
- Degraded: search unavailable shows the dialog's error notice; everything else works.
- Success: the overview, with the Use sidebar the reader keeps on every Use page and Maintain one click away.
2. Use page — /<slug>/use/<line>/<page>
Phone width: the sidebar is a drawer; the version menu and track switch sit at its top.
Desktop: the sidebar is always visible with the menu and switch at its top. Under the page description, a line states the version the page documents (invariant 3).
States
- Empty: a line with only its index page shows that page and a one-link sidebar.
- Loading: none; prerendered.
- Not found: a missing page gets the site's 404.
- Refused: not applicable today.
- Error: the site's error page; no raw error text.
- Degraded: search unavailable shows the dialog's notice.
- Success: the page, with the current line selected and Use highlighted.
3. Version menu — opened from the sidebar
Lines are listed latest first, then dev, then older lines in the order of use/meta.json
pages, or newest version first. Each option shows the line's name and names its channel in
words, not by colour alone.
States
- Empty: a package with one line shows a menu with that one line.
- Success: choosing a line opens the same page in that line when it exists, otherwise that line's first page.
4. In development page — /<slug>/use/dev/<page>
Older lines show the same shape: "Older version — This page documents ledgerly 3.6.2. Read this page for 4.0.1, the latest release."
States
- Success: the banner sits under the title and links to the same page in the latest line, or that line's first page. An unreleased package with no latest line shows the banner without the link.
- Other states: as the Use page.
5. Maintain page — /<slug>/maintain/<page>
The Maintain track is not versioned: it describes the repository's default branch, so it has no version menu and no version line.
States
- Empty: a package without a Maintain track has no switch; its Maintain URLs get the 404.
- Other states: as the Use page.
6. Demo page — /<slug>/use/<line>/demo
Not published: how a demo runs needs its own ADR, since ADR-0011's embed takes only diagrams.
When a line has a demo.mdx page, the home page catalogue links to it.