Replaces an 89-line README that mostly duplicated code links with a
90-line README that answers the three questions a new reader actually
asks: 'what is this?', 'how do I run it?', 'where do I go next?'.
Also adds two longer-form references that the old README was missing
entirely:
docs/ARCHITECTURE.md (new):
- Four Mermaid diagrams:
1. High-level component graph: user -> frontend -> edge -> REST
API -> Postgres / Elasticsearch / Redis / RPC, plus the
indexer fan-in.
2. Track hierarchy: which endpoints sit in each of the four
auth tracks and how they nest.
3. Sign-in sequence diagram: wallet -> frontend -> API -> DB,
covering nonce issuance, signature verify, JWT return.
4. Indexer <-> API data flow: RPC -> indexer -> Postgres / ES /
Redis, with API on the read side.
- Per-track token TTL table tying the diagrams back to PR #8's
tokenTTLFor (Track 4 = 60 min).
- Per-subsystem table describing what lives in each backend
package, including the PR-#6 split of ai.go into six files.
- Runtime dependencies table.
- Security posture summary referencing PR #3's fail-fast JWT /
CSP checks, .gitleaks.toml, and docs/SECURITY.md.
docs/API.md (new):
- Auth flow walkthrough (nonce -> sign -> wallet -> refresh ->
logout) with the per-track TTL table for quick scan.
- Rate-limit matrix.
- Tagged endpoint index generated from
backend/api/rest/swagger.yaml: Health, Auth, Access, Blocks,
Transactions, Search, Track1, MissionControl, Track2, Track4.
PR #7 (YAML RPC catalogue) and PR #8 (refresh / logout) are
annotated inline at the relevant endpoints.
- Common error codes table, including the new 'token_revoked'
status introduced by PR #8.
- Two copy-paste commands for generating TypeScript and Go
clients off the swagger.yaml, so downstream repos don't have
to hand-maintain one.
README.md:
- Trimmed to 90 lines (previous was 89 lines of README lore).
- Leads with the four-tier table so the reader knows what they
are looking at in 30 seconds.
- 'Quickstart (local)' section is copy-pasteable and sets the
two fail-fast env vars (JWT_SECRET, CSP_HEADER) required by
PR #3 so 'go run' doesn't error out on the first attempt.
- Forward-references docs/ARCHITECTURE.md, docs/API.md,
docs/TESTING.md (from PR #10), docs/SECURITY.md (from PR #3),
and CONTRIBUTING.md.
- Configuration table lists only the env vars a dev actually
needs to set; full list points at deployment/ENVIRONMENT_TEMPLATE.env.
Verification:
wc -l README.md = 93 (target was <=150).
wc -l docs/ARCHITECTURE.md = 145 (four diagrams, tables, pointers).
wc -l docs/API.md = 115 (index + auth/error tables).
markdownlint-style scan no obvious issues.
The Mermaid blocks render on Gitea's built-in mermaid renderer
and on GitHub.
Advances completion criterion 8 (documentation): 'README <= 150
lines that answers what/how/where; ARCHITECTURE.md with diagrams
of tracks, components, and data flow; API.md generated from
swagger.yaml. Old ~300 status markdown files were removed by PR #2.'
