Files

Devin 08946a1971 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

3.0 KiB

Raw Blame History

SolaceScan Explorer

Multi-tier block explorer and access-control plane for Chain 138.

Four access tiers:

Track	Who	Auth	Examples
1	Public	None	`/blocks`, `/transactions`, `/search`
2	Wallet-verified	SIWE JWT	RPC API keys, subscriptions, usage reports
3	Analytics	SIWE JWT (admin or billed)	Advanced analytics, audit logs
4	Operator	SIWE JWT (`operator.*`)	`run-script`, mission-control, ops

See docs/ARCHITECTURE.md for diagrams of how the tracks, services, and data stores fit together, and docs/API.md for the endpoint reference generated from backend/api/rest/swagger.yaml.

Repository layout

backend/           Go 1.23 services (api/rest, indexer, auth, analytics, ...)
frontend/          Next.js 14 pages-router app
deployment/        docker-compose and deploy manifests
scripts/           e2e specs, smoke scripts, operator runbooks
docs/              Architecture, API, testing, security, runbook

Quickstart (local)

Prereqs: Docker (+ compose), Go 1.23.x, Node 20.

# 1. Infra deps
docker compose -f deployment/docker-compose.yml up -d postgres elasticsearch redis

# 2. DB schema
cd backend && go run database/migrations/migrate.go && cd ..

# 3. Backend (port 8080)
export JWT_SECRET=$(openssl rand -hex 32)
export CSP_HEADER="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' http://localhost:8080 ws://localhost:8080"
cd backend/api/rest && go run . &

# 4. Frontend (port 3000)
cd frontend && npm ci && npm run dev

Or let make e2e-full do everything end-to-end and run Playwright against the stack (see docs/TESTING.md).

Configuration

Every credential, URL, and RPC endpoint is an env var. There is no in-repo production config. Minimum required by a non-dev binary:

Var	Purpose	Notes
`JWT_SECRET`	HS256 wallet-auth signing key	Fail-fast if empty
`CSP_HEADER`	`Content-Security-Policy` response header	Fail-fast if empty
`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME`	Postgres connection
`REDIS_HOST` / `REDIS_PORT`	Redis cache
`ELASTICSEARCH_URL`	Indexer / search backend
`RPC_URL` / `WS_URL`	Upstream Chain 138 RPC
`RPC_PRODUCTS_PATH`	Optional override for `backend/config/rpc_products.yaml`	PR #7

Full list: deployment/ENVIRONMENT_TEMPLATE.env.

Testing

# Unit tests + static checks
cd backend && go test ./... && staticcheck ./... && govulncheck ./...
cd frontend && npm test && npm run test:unit

# Production canary
EXPLORER_URL=https://explorer.d-bis.org make test-e2e

# Full local stack + Playwright
make e2e-full

See docs/TESTING.md.

Contributing

Branching, PR template, CI gates, secret handling: see CONTRIBUTING.md. Never commit real credentials — .gitleaks.toml will block the push and rotation steps live in docs/SECURITY.md.

Licence

MIT.

3.0 KiB Raw Blame History