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 START_HERE.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

• docs/README.md — Documentation overview and index
• docs/EXPLORER_API_ACCESS.md — API access, 502 fix, CSP, frontend deploy
• START_HERE.md — Quick start with all commands
• COMPLETE_DEPLOYMENT.md — Detailed deployment steps
• DEPLOYMENT_COMPLETE_FINAL.md — Final status report
• README_DEPLOYMENT.md — Deployment quick reference
• deployment/DEPLOYMENT_GUIDE.md — Full LXC/Nginx/Cloudflare deployment guide
• docs/INDEX.md — Bridge and operations doc index

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

• Database User: explorer
• Database Password: ***REDACTED-LEGACY-PW***
• RPC URL: http://192.168.11.250:8545
• Chain ID: 138
• Port: 8080

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!