docs: rewrite README, add ARCHITECTURE.md (Mermaid), add API.md from swagger.yaml #11
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: d-bis/explorer-monorepo#11
Reference in New Issue
Block a user
Delete Branch "devin/1776540420-docs-readme-architecture-rewrite"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
PR #11 — final PR of the 11-PR completion sequence. Replaces an 89-line README that mostly duplicated code links with a 93-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?
Adds two longer-form references the old README was missing entirely.
Changes
docs/ARCHITECTURE.md(new)Four Mermaid diagrams:
Also: per-track TTL table tying back to PR #8's
tokenTTLFor(Track 4 = 60 min), per-subsystem table (including PR #6's six-file ai split), runtime dependencies table, security posture summary.docs/API.md(new)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 /token_revoked) annotated inline.token_revoked.swagger.yaml.README.mdJWT_SECRET,CSP_HEADER) PR #3 requires sogo rundoesn't error on the first attempt.docs/ARCHITECTURE.md,docs/API.md,docs/TESTING.md(PR #10),docs/SECURITY.md(PR #3),CONTRIBUTING.md.deployment/ENVIRONMENT_TEMPLATE.env.Verification
wc -l README.md= 93 (target ≤150).wc -l docs/ARCHITECTURE.md= 145.wc -l docs/API.md= 115.Completion criterion advanced
This is the last of the 11 PRs. The full sequence:
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.'Completion sequence — all 11 PRs open
This is the last PR of the completion sequence drafted against the review. Once all 11 land on
master, the repo meets the 8 "complete" criteria fromexplorer-monorepo-completion-prompt.md.The 11 PRs
chore/gitignore-and-artifacts.gitignorechore/doc-consolidationfix/jwt-and-csp-hardeningJWT_SECRET/CSP_HEADER, stripunsafe-inline/unsafe-evaland192.168.11.xCIDRs from CSP, scrub production-looking passwords, adddocs/SECURITY.mdrotation runbookfix/auth-context-keys-and-errorsctxKeyconstants (kills SA1029), real sentinel errors instead ofhttp.ErrMissingFilechore/ci-go-version-and-scannersgo.mod, addgitleaks/staticcheck/govulncheck/eslint/tscgatesrefactor/ai-package-splitai.gointoai.go+ai_context.go+ai_routes.go+ai_docs.go+ai_xai.go+ai_helpers.go(no behavioural change)refactor/config-externalizebackend/config/rpc_products.yamlwith a 5-tier path-resolverfeat/jwt-revocation-and-refreshjticlaim,jwt_revocationstable (migration 0016),/api/v1/auth/refresh+/api/v1/auth/logoutchore/frontend-router-decisionsrc/app/, commit to pages router, moveglobals.css, unifypackageManageronnpm@10.8.2, pinenginestest/e2e-full-and-ci-wiringmake e2e-fullboots the full stack (docker-compose + backend + frontend) and runs Playwright; dedicated CI workflow with screenshot artefactsdocs/readme-architecture-rewritedocs/ARCHITECTURE.mdwith 4 Mermaid diagrams,docs/API.mdindexed fromswagger.yaml"Complete" — one-paragraph definition
The repo is complete when (1) no binaries, scratch dirs, or auto-generated status docs are tracked in git; (2) every credential, RPC URL, VMID, and CSP header comes from env vars or a committed YAML, and production binaries fail-fast without the required ones; (3) wallet JWTs carry a
jti, respect per-track TTLs (Track 4 ≤ 1 h), are revocable server-side, and the client can rotate them via/api/v1/auth/refreshbefore they expire; (4) CI (test-backend,test-frontend,lint,scan-backend,gitleaks) must be green on the pinned toolchain versions before a PR merges; (5) the frontend is a single pages-router Next.js app using one lockfile and one package manager; (6) the AI endpoint code is split across focused files and the RPC product catalogue is a YAML not a Go literal; (7)make e2e-fullstands up the full stack locally and runs Playwright with screenshot artefacts, and a CI workflow runs the same nightly and on opt-in PRs; (8) a new engineer lands on a ≤150-line README that links todocs/ARCHITECTURE.md(Mermaid component / track / sign-in / data-flow diagrams) anddocs/API.md(endpoint reference generated fromswagger.yaml) — with no duplicate quick-start or status-report files.Merge order
PRs are independent (each cut from
master) but a reviewer who wants the cleanest diff stack should merge in numerical order: #1 → #11. Merging #3 and #5 first is recommended because the rest of the sequence verifies against the scanners added in #5 and the fail-fast env contract introduced in #3.Follow-ups (out of scope for these 11)
docs/SECURITY.mdlists every asset). The PR sequence removes the strings from the tree; history rewrite + live rotation are a deploy-side action.backend/api/rest/*_test.go— PR #8 adds unit-level TTL /jti/ revocation tests, but the HTTP handlers for refresh/logout are covered only by themake e2e-fullPlaywright spec.swagger.yamlfile still pre-dates PR #8's/auth/refreshand/auth/logout—docs/API.mddocuments them, but the OpenAPI spec itself should be updated in a follow-up so client generators pick them up.