Devin
08946a1971
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.'
Explorer Monorepo – Documentation
Overview of documentation for the ChainID 138 Explorer (SolaceScan).
Entry points
| Doc | Description |
|---|---|
| INDEX.md | Full documentation index (bridge, setup, verification, operations) |
| EXPLORER_API_ACCESS.md | API access, 502 fix, CSP, frontend deploy for https://blockscout.defi-oracle.io |
| ../README.md | Project README: quick start, frontend, architecture, config |
Frontend
| Doc | Description |
|---|---|
| ../frontend/FRONTEND_REVIEW.md | Frontend code review (Next app + legacy SPA) |
| ../frontend/FRONTEND_TASKS_AND_REVIEW.md | Task list C1–L4 and detail review |
Deploy the current Next standalone frontend (VMID 5000):
./scripts/deploy-next-frontend-to-vmid5000.sh
Nginx should preserve /api, /api/config/*, /explorer-api/*, /token-aggregation/api/v1/*, /snap/, and /health, then proxy / and /_next/ using deployment/common/nginx-next-frontend-proxy.conf.
Legacy static SPA compatibility assets:
The historical static SPA (frontend/public/index.html +
frontend/public/explorer-spa.js) remains in-repo for compatibility and audit
reference only. The old static deploy scripts are deprecated shims and are not
supported deployment targets.
Full explorer/API fix (Blockscout + nginx + frontend):
./scripts/complete-explorer-api-access.sh
Deployment
| Doc | Description |
|---|---|
| ../README_DEPLOYMENT.md | Deployment quick reference |
| ../deployment/DEPLOYMENT_GUIDE.md | Full LXC + Nginx + Cloudflare deployment guide |
| ../QUICKSTART.md | Quick start (deps, infra, dev services) |
Other
- Bridge / WETH: See INDEX.md for bridge setup, verification, and operations.
- Specs: specs/ for infrastructure and multichain specs.
- CCIP, Blockscout, etc.: See files in this directory and the repo root.
Last updated: 2026-04-11