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.'
94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
# 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](docs/ARCHITECTURE.md) for diagrams of how the
|
|
tracks, services, and data stores fit together, and [docs/API.md](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.
|
|
|
|
```bash
|
|
# 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](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
|
|
|
|
```bash
|
|
# 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](docs/TESTING.md).
|
|
|
|
## Contributing
|
|
|
|
Branching, PR template, CI gates, secret handling: see
|
|
[CONTRIBUTING.md](CONTRIBUTING.md). Never commit real credentials —
|
|
`.gitleaks.toml` will block the push and rotation steps live in
|
|
[docs/SECURITY.md](docs/SECURITY.md).
|
|
|
|
## Licence
|
|
|
|
MIT.
|