d-bis/explorer-monorepo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.'
This commit is contained in:
Devin
2026-04-18 19:29:36 +00:00
parent 7a603e1f96
commit 1721f6b20c
3 changed files with 379 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
docs/API.md Normal file
View File

@@ -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
```

162
docs/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,162 @@
# Architecture
## Overview
SolaceScan is a four-tier block explorer + access-control plane for
Chain 138. Every request is classified into one of four **tracks**;
higher tracks require stronger authentication and hit different
internal subsystems.
```mermaid
flowchart LR
U[User / wallet / operator] -->|HTTPS| FE[Next.js frontend<br/>:3000]
U -->|direct API<br/>or SDK| EDGE[Edge / nginx<br/>:443]
FE --> EDGE
EDGE --> API[Go REST API<br/>backend/api/rest :8080]
API --> PG[(Postgres +<br/>TimescaleDB)]
API --> ES[(Elasticsearch)]
API --> RD[(Redis)]
API --> RPC[(Chain 138 RPC<br/>core / alltra / thirdweb)]
IDX[Indexer<br/>backend/indexer] --> PG
IDX --> ES
RPC --> IDX
subgraph Access layer
EDGE -->|auth_request| VK[validate-key<br/>/api/v1/access/internal/validate-key]
VK --> API
end
```
## Tracks
```mermaid
flowchart TB
subgraph Track1[Track 1 — public, no auth]
T1A[/blocks]
T1B[/transactions]
T1C[/search]
T1D[/api/v1/track1/*]
end
subgraph Track2[Track 2 — wallet-verified]
T2A[Subscriptions]
T2B[API key lifecycle]
T2C[Usage + audit self-view]
end
subgraph Track3[Track 3 — analytics]
T3A[Advanced analytics]
T3B[Admin audit]
T3C[Admin subscription review]
end
subgraph Track4[Track 4 — operator]
T4A[/api/v1/track4/operator/run-script]
T4B[Mission-control SSE]
T4C[Ops tooling]
end
Track1 --> Track2 --> Track3 --> Track4
```
Authentication for tracks 2–4 is SIWE-style: client hits
`/api/v1/auth/nonce`, signs the nonce with its wallet, posts the
signature to `/api/v1/auth/wallet`, gets a JWT back. JWTs carry the
resolved `track` claim and a `jti` for server-side revocation (see
`backend/auth/wallet_auth.go`).
### Per-track token TTLs
| Track | TTL | Rationale |
|------|-----|-----------|
| 1 | 12h | Public / long-lived session OK |
| 2 | 8h | Business day |
| 3 | 4h | Analytics session |
| 4 | **60 min** | Operator tokens are the most dangerous; short TTL + `POST /api/v1/auth/refresh` |
Revocation lives in `jwt_revocations` (migration `0016`). Logging out
(`POST /api/v1/auth/logout`) inserts the token's `jti` so subsequent
validation rejects it.
## Sign-in flow (wallet)
```mermaid
sequenceDiagram
autonumber
actor W as Wallet
participant FE as Frontend
participant API as REST API
participant DB as Postgres
W->>FE: connect / sign-in
FE->>API: POST /api/v1/auth/nonce {address}
API->>DB: insert wallet_nonces(address, nonce, expires_at)
API-->>FE: {nonce}
FE->>W: signTypedData/personal_sign(nonce)
W-->>FE: signature
FE->>API: POST /api/v1/auth/wallet {address, nonce, signature}
API->>API: ecrecover → verify address
API->>DB: consume nonce; resolve user track
API-->>FE: {token, expiresAt, track, permissions}
FE-->>W: session active
```
## Data flow (indexer ↔ API)
```mermaid
flowchart LR
RPC[(Chain 138 RPC)] -->|new blocks| IDX[Indexer]
IDX -->|INSERT blocks, txs, logs| PG[(Postgres)]
IDX -->|bulk index| ES[(Elasticsearch)]
IDX -->|invalidate| RD[(Redis)]
API[REST API] -->|SELECT| PG
API -->|search, facets| ES
API -->|cached RPC proxy| RD
API -->|passthrough for deep reads| RPC
```
## Subsystems
- **`backend/api/rest`** — HTTP API. One package; every handler lives
under `backend/api/rest/*.go`. AI endpoints were split into
`ai.go` + `ai_context.go` + `ai_routes.go` + `ai_docs.go` +
`ai_xai.go` + `ai_helpers.go` by PR #6 to keep file size
manageable.
- **`backend/auth`** — wallet auth (nonce issue, signature verify,
JWT issuance / validation / revocation / refresh).
- **`backend/indexer`** — Chain 138 block/tx/log indexer, writes
Postgres + Elasticsearch, invalidates Redis.
- **`backend/analytics`** — longer-running queries: token distribution,
holder concentration, liquidity-pool aggregates.
- **`backend/api/track4`** — operator-scoped endpoints
(`run-script`, mission-control).
- **`frontend`** — Next.js 14 pages-router app. Router decision
(PR #9) is final: no `src/app/`.
## Runtime dependencies
| Service | Why |
|---------|-----|
| Postgres (+ TimescaleDB) | Chain data, users, subscriptions, `jwt_revocations` |
| Elasticsearch | Full-text search, facets |
| Redis | Response cache, rate-limit counters, SSE fan-out |
| Chain 138 RPC | Upstream source of truth; three lanes — core / alltra / thirdweb — catalogued in `backend/config/rpc_products.yaml` |
## Deployment
See [deployment/README.md](../deployment/README.md) for compose and
production deploy details. The `deployment/docker-compose.yml` file
is the reference local stack and is what `make e2e-full` drives.
## Security posture
- `JWT_SECRET` and `CSP_HEADER` are **fail-fast** — a production
binary refuses to start without them (PR #3).
- Secrets never live in-repo; `.gitleaks.toml` blocks known-bad
patterns at commit time.
- Rotation checklist: [docs/SECURITY.md](SECURITY.md).
- Track-4 token TTL capped at 60 min; every issued token is
revocable by `jti`.