Devin
40c9af678f
Before: 335 tracked .md files; top level had 14 README-like docs; docs/ contained ~234 files, most of them auto/LLM-generated status reports (ALL_*_COMPLETE*, *_FIX*, DEPLOYMENT_*_FINAL*, etc.). After: 132 tracked .md files. Repo now has exactly five top-level docs: README.md, QUICKSTART.md, RUNBOOK.md, CONTRIBUTING.md, CHANGELOG.md (moved up from docs/). Keeper philosophy in docs/: - API, CCIP (ops + security + receiver/router refs), Chainlist refs, compliance, deployment (guides not status), database connection, legal compliance, metamask integration, production checklist, tiered-architecture implementation/setup, reusable-components plan, token-mechanism doc, wrap-and-bridge operational reference, plus docs/specs/** and docs/api/ / docs/openapi/ trees. Deleted (git history preserves provenance): - All 'ALL_*_COMPLETE*' / '*_FIX*' / '*_FIXED*' / '*_FINAL*' / '*_STATUS*' / '*_PROGRESS*' / '*_SUMMARY*' files. - BLOCKSCOUT_*_FIX / _CRASH / _INITIALIZATION / _SCHEMA / _YAML / _SKIP / _NEXT_STEPS / _START_AND_BUILD / _DATABASE_CREDENTIALS (the last contained passwords). - CCIP_IMPLEMENTATION_* / CCIP_CURRENT_STATUS / CCIP_GAP_* (gap analyses are not a sustained reference). - NPMPLUS_CREDENTIALS_GUIDE.md (contained creds). - LETSENCRYPT_CONFIGURATION_GUIDE.md (contained creds; will be re-introduced as runbook content post-secrets-scrub). - docs/diagnostic-reports/, docs/feature-flags/ (run-time artifacts). README.md: dead links (START_HERE, README_DEPLOYMENT, COMPLETE_DEPLOYMENT, DEPLOYMENT_COMPLETE_FINAL) replaced with links to the five canonical top-level docs + docs/ index.
89 lines
4.4 KiB
Markdown
89 lines
4.4 KiB
Markdown
# SolaceScan Explorer - Tiered Architecture
|
||
|
||
## 🚀 Quick Start - Complete Deployment
|
||
|
||
**Execute this single command to complete all deployment steps:**
|
||
|
||
```bash
|
||
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](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_REVIEW.md), [frontend/FRONTEND_TASKS_AND_REVIEW.md](frontend/FRONTEND_TASKS_AND_REVIEW.md)
|
||
|
||
## Documentation
|
||
|
||
- **[QUICKSTART.md](QUICKSTART.md)** — 5-minute bring-up for local development
|
||
- **[RUNBOOK.md](RUNBOOK.md)** — Operational runbook for the live deployment
|
||
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution workflow and conventions
|
||
- **[CHANGELOG.md](CHANGELOG.md)** — Release notes
|
||
- **[docs/README.md](docs/README.md)** — Documentation index (API, architecture, CCIP, legal)
|
||
- **[docs/EXPLORER_API_ACCESS.md](docs/EXPLORER_API_ACCESS.md)** — API access, CSP, frontend deploy
|
||
- **[deployment/DEPLOYMENT_GUIDE.md](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
|
||
|
||
- **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:
|
||
|
||
```bash
|
||
git clone --recurse-submodules <repo-url>
|
||
# or after clone:
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
See [docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md](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!**
|