explorer-monorepo/docs/ARCHITECTURE.md

Architecture

Overview

SolaceScan is a four-tier block explorer + access-control plane for Chain 138. Every request is classified into one of four tracks; higher tracks require stronger authentication and hit different internal subsystems.

flowchart LR
    U[User / wallet / operator] -->|HTTPS| FE[Next.js frontend<br/>:3000]
    U -->|direct API<br/>or SDK| EDGE[Edge / nginx<br/>:443]
    FE --> EDGE
    EDGE --> API[Go REST API<br/>backend/api/rest :8080]

    API --> PG[(Postgres +<br/>TimescaleDB)]
    API --> ES[(Elasticsearch)]
    API --> RD[(Redis)]
    API --> RPC[(Chain 138 RPC<br/>core / alltra / thirdweb)]

    IDX[Indexer<br/>backend/indexer] --> PG
    IDX --> ES
    RPC --> IDX

    subgraph Access layer
      EDGE -->|auth_request| VK[validate-key<br/>/api/v1/access/internal/validate-key]
      VK --> API
    end

Tracks

flowchart TB
    subgraph Track1[Track 1 — public, no auth]
      T1A[/blocks]
      T1B[/transactions]
      T1C[/search]
      T1D[/api/v1/track1/*]
    end

    subgraph Track2[Track 2 — wallet-verified]
      T2A[Subscriptions]
      T2B[API key lifecycle]
      T2C[Usage + audit self-view]
    end

    subgraph Track3[Track 3 — analytics]
      T3A[Advanced analytics]
      T3B[Admin audit]
      T3C[Admin subscription review]
    end

    subgraph Track4[Track 4 — operator]
      T4A[/api/v1/track4/operator/run-script]
      T4B[Mission-control SSE]
      T4C[Ops tooling]
    end

    Track1 --> Track2 --> Track3 --> Track4

Authentication for tracks 2–4 is SIWE-style: client hits /api/v1/auth/nonce, signs the nonce with its wallet, posts the signature to /api/v1/auth/wallet, gets a JWT back. JWTs carry the resolved track claim and a jti for server-side revocation (see backend/auth/wallet_auth.go).

Per-track token TTLs

Track	TTL	Rationale
1	12h	Public / long-lived session OK
2	8h	Business day
3	4h	Analytics session
4	60 min	Operator tokens are the most dangerous; short TTL + POST /api/v1/auth/refresh

Revocation lives in jwt_revocations (migration 0016). Logging out (POST /api/v1/auth/logout) inserts the token's jti so subsequent validation rejects it.

Sign-in flow (wallet)

sequenceDiagram
    autonumber
    actor W as Wallet
    participant FE as Frontend
    participant API as REST API
    participant DB as Postgres

    W->>FE: connect / sign-in
    FE->>API: POST /api/v1/auth/nonce {address}
    API->>DB: insert wallet_nonces(address, nonce, expires_at)
    API-->>FE: {nonce}
    FE->>W: signTypedData/personal_sign(nonce)
    W-->>FE: signature
    FE->>API: POST /api/v1/auth/wallet {address, nonce, signature}
    API->>API: ecrecover → verify address
    API->>DB: consume nonce; resolve user track
    API-->>FE: {token, expiresAt, track, permissions}
    FE-->>W: session active

Data flow (indexer ↔ API)

flowchart LR
    RPC[(Chain 138 RPC)] -->|new blocks| IDX[Indexer]
    IDX -->|INSERT blocks, txs, logs| PG[(Postgres)]
    IDX -->|bulk index| ES[(Elasticsearch)]
    IDX -->|invalidate| RD[(Redis)]

    API[REST API] -->|SELECT| PG
    API -->|search, facets| ES
    API -->|cached RPC proxy| RD
    API -->|passthrough for deep reads| RPC

Subsystems

• backend/api/rest — HTTP API. One package; every handler lives under backend/api/rest/*.go. AI endpoints were split into ai.go + ai_context.go + ai_routes.go + ai_docs.go + ai_xai.go + ai_helpers.go by PR #6 to keep file size manageable.
• backend/auth — wallet auth (nonce issue, signature verify, JWT issuance / validation / revocation / refresh).
• backend/indexer — Chain 138 block/tx/log indexer, writes Postgres + Elasticsearch, invalidates Redis.
• backend/analytics — longer-running queries: token distribution, holder concentration, liquidity-pool aggregates.
• backend/api/track4 — operator-scoped endpoints (run-script, mission-control).
• frontend — Next.js 14 pages-router app. Router decision (PR #9) is final: no src/app/.

Runtime dependencies

Service	Why
Postgres (+ TimescaleDB)	Chain data, users, subscriptions, jwt_revocations
Elasticsearch	Full-text search, facets
Redis	Response cache, rate-limit counters, SSE fan-out
Chain 138 RPC	Upstream source of truth; three lanes — core / alltra / thirdweb — catalogued in backend/config/rpc_products.yaml

Deployment

See deployment/README.md for compose and production deploy details. The deployment/docker-compose.yml file is the reference local stack and is what make e2e-full drives.

Security posture

• JWT_SECRET and CSP_HEADER are fail-fast — a production binary refuses to start without them (PR #3).
• Secrets never live in-repo; .gitleaks.toml blocks known-bad patterns at commit time.
• Rotation checklist: docs/SECURITY.md.
• Track-4 token TTL capped at 60 min; every issued token is revocable by jti.