SolaceScan Explorer - Tiered Architecture

🚀 Quick Start - Complete Deployment

Execute this single command to complete all deployment steps:

cd ~/projects/proxmox/explorer-monorepo
bash EXECUTE_DEPLOYMENT.sh

What This Does

1. ✅ Tests database connection
2. ✅ Runs migration (if needed)
3. ✅ Stops existing server
4. ✅ Starts server with database
5. ✅ Tests all endpoints
6. ✅ Provides status summary

Manual Execution

If the script doesn't work, see QUICKSTART.md for step-by-step manual commands.

Frontend

• Production (canonical target): the current Next.js standalone frontend in frontend/src/, built from frontend/ with npm run build and deployed to VMID 5000 as a Node service behind nginx.
• Canonical deploy script: ./scripts/deploy-next-frontend-to-vmid5000.sh
• Canonical nginx wiring: keep /api, /api/config/*, /explorer-api/*, /token-aggregation/api/v1/*, /snap/, and /health; proxy / and /_next/ to the frontend service using deployment/common/nginx-next-frontend-proxy.conf.
• Legacy fallback only: the static SPA (frontend/public/index.html + explorer-spa.js) remains in-repo for compatibility/reference, but it is not a supported primary deployment target.
• Architecture command center: frontend/public/chain138-command-center.html — tabbed Mermaid topology (Chain 138 hub, network, stack, flows, cross-chain, cW Mainnet, off-chain, integrations). Linked from the SPA More → Explore → Visual Command Center.
• Legacy static deploy scripts: ./scripts/deploy-frontend-to-vmid5000.sh and ./scripts/deploy.sh now fail fast with a deprecation message and point to the canonical Next.js deploy path.
• Frontend review & tasks: frontend/FRONTEND_REVIEW.md, frontend/FRONTEND_TASKS_AND_REVIEW.md

Documentation

• QUICKSTART.md — 5-minute bring-up for local development
• RUNBOOK.md — Operational runbook for the live deployment
• CONTRIBUTING.md — Contribution workflow and conventions
• CHANGELOG.md — Release notes
• docs/README.md — Documentation index (API, architecture, CCIP, legal)
• docs/EXPLORER_API_ACCESS.md — API access, CSP, frontend deploy
• deployment/DEPLOYMENT_GUIDE.md — Full LXC/Nginx/Cloudflare deployment guide

Architecture

• Track 1 (Public): RPC Gateway - No authentication required
• Track 2 (Approved): Indexed Explorer - Requires authentication
• Track 3 (Analytics): Analytics Dashboard - Requires Track 3+
• Track 4 (Operator): Operator Tools - Requires Track 4 + IP whitelist

Configuration

All secrets and environment-specific endpoints are read from environment variables — nothing is committed to this repo. See docs/SECURITY.md for the rotation checklist and docs/DATABASE_CONNECTION_GUIDE.md for setup.

Variable	Purpose	Example
DB_USER	Postgres role	explorer
DB_PASSWORD	Postgres password (required, no default)	—
DB_HOST	Postgres host	localhost
DB_NAME	Database name	explorer
RPC_URL	Besu / execution client RPC endpoint	http://rpc.internal:8545
CHAIN_ID	EVM chain ID	138
PORT	API listen port	8080
JWT_SECRET	HS256 signing key (≥32 bytes, required in prod)	—
CSP_HEADER	Content-Security-Policy header (required in prod)	—

Reusable libs (extraction)

Reusable components live under backend/libs/ and frontend/libs/ and may be split into separate repos and linked via git submodules. Clone with submodules:

git clone --recurse-submodules <repo-url>
# or after clone:
git submodule update --init --recursive

See docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md for the full plan.

Testing

• All unit/lint: make test — backend go test ./... and frontend npm test (lint + type-check).
• Backend: cd backend && go test ./... — API tests run without a real DB; health returns 200 or 503, DB-dependent endpoints return 503 when DB is nil.
• Frontend: cd frontend && npm run build or npm test — Next.js build (includes lint) or lint + type-check only.
• E2E: make test-e2e or npm run e2e from repo root — Playwright tests against https://blockscout.defi-oracle.io by default; use EXPLORER_URL=http://localhost:3000 for local.

Status

✅ All implementation complete
✅ All scripts ready
✅ All documentation complete
✅ Frontend: C1–C4, M1–M4, H4, H5, L2, L4 done; H1/H2/H3 (escapeHtml/safe href) in place; optional L1, L3 remain
✅ CI: backend + frontend tests; lint job runs go vet, npm run lint, npm run type-check
✅ Tests: make test, make test-e2e, make build all pass

Ready for deployment!