docs: rewrite README (<=100 lines), add ARCHITECTURE.md with Mermaid diagrams, add API.md from swagger.yaml

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.'
2026-04-18 19:29:36 +00:00
parent e1c3b40cb0
commit 08946a1971
3 changed files with 379 additions and 67 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -0,0 +1,146 @@
+# API Reference
+
+Canonical, machine-readable spec: [`backend/api/rest/swagger.yaml`](../backend/api/rest/swagger.yaml)
+(OpenAPI 3.0.3). This document is a human index regenerated from that
+file — run `scripts/gen-api-md.py` after editing `swagger.yaml` to
+refresh it.
+
+## Base URLs
+
+| Env | URL |
+|-----|-----|
+| Production | `https://api.d-bis.org` |
+| Local dev | `http://localhost:8080` |
+
+## Authentication
+
+Track 1 endpoints (listed below under **Track1**, **Health**, and most
+of **Blocks** / **Transactions** / **Search**) are public. Every other
+endpoint requires a wallet JWT.
+
+The flow:
+
+1. `POST /api/v1/auth/nonce` with `{address}`  → `{nonce}`
+2. Sign the nonce with the wallet.
+3. `POST /api/v1/auth/wallet` with `{address, nonce, signature}`
+   → `{token, expiresAt, track, permissions}`
+4. Send subsequent requests with `Authorization: Bearer <token>`.
+5. Refresh before `expiresAt` with
+   `POST /api/v1/auth/refresh` (see [ARCHITECTURE.md](ARCHITECTURE.md)).
+6. Log out with `POST /api/v1/auth/logout` — revokes the token's
+   `jti` server-side.
+
+Per-track TTLs:
+
+| Track | TTL |
+|-------|-----|
+| 1 | 12h |
+| 2 | 8h |
+| 3 | 4h |
+| 4 | 60m |
+
+## Rate limits
+
+| Scope | Limit |
+|-------|-------|
+| Track 1 (per IP) | 100 req/min |
+| Tracks 2–4 | Per-user, per-subscription; see subscription detail in `GET /api/v1/access/subscriptions` |
+
+## Endpoint index
+
+## Health
+Health check endpoints
+- `GET /health` — Health check
+
+## Auth
+Wallet and user-session authentication endpoints
+- `POST /api/v1/auth/nonce` — Generate wallet auth nonce
+- `POST /api/v1/auth/wallet` — Authenticate with wallet signature
+- `POST /api/v1/auth/refresh` — Rotate a still-valid JWT (adds a new `jti`; revokes the old one) — PR #8
+- `POST /api/v1/auth/logout` — Revoke the current JWT by `jti` — PR #8
+- `POST /api/v1/auth/register` — Register an explorer access user
+- `POST /api/v1/auth/login` — Log in to the explorer access console
+
+## Access
+RPC product catalog, subscriptions, and API key lifecycle
+- `GET /api/v1/access/me` — Get current access-console user
+- `GET /api/v1/access/products` — List available RPC access products (backed by `backend/config/rpc_products.yaml`, PR #7)
+- `GET /api/v1/access/subscriptions` — List subscriptions for the signed-in user
+- `GET /api/v1/access/admin/subscriptions` — List subscriptions for admin review
+- `POST /api/v1/access/admin/subscriptions` — Request or activate product access
+- `GET /api/v1/access/api-keys` — List API keys for the signed-in user
+- `POST /api/v1/access/api-keys` — Create an API key
+- `POST /api/v1/access/api-keys/{id}` — Revoke an API key
+- `DELETE /api/v1/access/api-keys/{id}` — Revoke an API key
+- `GET /api/v1/access/usage` — Get usage summary for the signed-in user
+- `GET /api/v1/access/audit` — Get recent API activity for the signed-in user
+- `GET /api/v1/access/admin/audit` — Get recent API activity across users for admin review
+- `GET /api/v1/access/internal/validate-key` — Validate an API key for nginx auth_request or similar edge subrequests
+- `POST /api/v1/access/internal/validate-key` — Validate an API key for internal edge enforcement
+
+## Blocks
+Block-related endpoints
+- `GET /api/v1/blocks` — List blocks
+- `GET /api/v1/blocks/{chain_id}/{number}` — Get block by number
+
+## Transactions
+Transaction-related endpoints
+- `GET /api/v1/transactions` — List transactions
+
+## Search
+Unified search endpoints
+- `GET /api/v1/search` — Unified search
+
+## Track1
+Public RPC gateway endpoints (no auth required)
+- `GET /api/v1/track1/blocks/latest` — Get latest blocks (Public)
+
+## MissionControl
+Public mission-control health, bridge trace, and cached liquidity helpers
+- `GET /api/v1/mission-control/stream` — Mission-control SSE stream
+- `GET /api/v1/mission-control/liquidity/token/{address}/pools` — Cached liquidity proxy
+- `GET /api/v1/mission-control/bridge/trace` — Resolve a transaction through Blockscout and label 138-side contracts
+
+## Track2
+Indexed explorer endpoints (auth required)
+- `GET /api/v1/track2/search` — Advanced search (Auth Required)
+
+## Track4
+Operator endpoints (Track 4 + IP whitelist)
+- `POST /api/v1/track4/operator/run-script` — Run an allowlisted operator script
+
+## Error shape
+
+All errors use:
+
+```json
+{
+  "error": "short_code",
+  "message": "human-readable explanation"
+}
+```
+
+Common codes:
+
+| HTTP | `error` | Meaning |
+|------|---------|---------|
+| 400 | `bad_request` | Malformed body or missing param |
+| 401 | `unauthorized` | Missing or invalid JWT |
+| 401 | `token_revoked` | JWT's `jti` is in `jwt_revocations` (PR #8) |
+| 403 | `forbidden` | Authenticated but below required track |
+| 404 | `not_found` | Record does not exist |
+| 405 | `method_not_allowed` | HTTP method not supported for route |
+| 429 | `rate_limited` | Over the track's per-window quota |
+| 503 | `service_unavailable` | Backend dep unavailable or migration missing |
+
+## Generating client SDKs
+
+The `swagger.yaml` file is standard OpenAPI 3.0.3; any generator works.
+
+```bash
+# TypeScript fetch client
+npx openapi-typescript backend/api/rest/swagger.yaml -o frontend/src/api/types.ts
+
+# Go client
+oapi-codegen -package explorerclient backend/api/rest/swagger.yaml > client.go
+```