Grantfox Analytics Dashboard

A full-stack analytics platform for the Stellar blockchain. Ingests ledger data in real-time, exposes a GraphQL API with subscriptions, and serves a React dashboard with live charts, search, and account/transaction drill-downs.

---

Architecture

Stellar Horizon API
        │
        ▼
 packages/indexer          ← streams & validates ledger data
        │
        ▼
   PostgreSQL  ◄──── Redis (cache)
        │                  │
        └──────► packages/api (Apollo GraphQL + WebSocket)
                        │
                        ▼
              packages/frontend (React + Vite)

Monorepo packages

Package	Description
packages/shared	Shared TypeScript types, Zod schemas, constants
packages/indexer	Blockchain data ingestion service
packages/api	Apollo GraphQL API with auth and subscriptions
packages/frontend	React dashboard (Vite + Tailwind + Zustand)
packages/e2e	Playwright end-to-end test suite

The top-level api/, frontend/, indexer/, and shared/ directories are legacy scaffolding kept for reference. The packages/ directory is the active codebase.

---

Prerequisites

• Node.js 20+
• pnpm 9.12+
• Docker (for PostgreSQL and Redis)

---

Quick Start

1. Install dependencies

pnpm install

2. Start infrastructure

docker compose up -d postgres redis

3. Copy and configure environment variables

cp packages/api/.env.example packages/api/.env
cp packages/indexer/.env.example packages/indexer/.env

Minimum required variables:

DATABASE_URL=postgres://grantfox:grantfox@localhost:5432/grantfox_analytics
REDIS_URL=redis://localhost:6379
STELLAR_NETWORK=testnet

4. Run database migrations

pnpm db:migrate

5. Start all services

pnpm dev

Or start services individually:

pnpm dev:indexer   # Blockchain ingestion (port 3001)
pnpm dev:api       # GraphQL API (port 4000)
pnpm dev:frontend  # React dashboard (port 5173)

---

Endpoints

Service	URL
GraphQL playground	http://localhost:4000/graphql
Frontend dashboard	http://localhost:5173
API health check	http://localhost:4000/health
Indexer health	http://localhost:3001/health
Prometheus metrics	http://localhost:3001/metrics

---

Development

Running tests

pnpm test            # all unit tests
pnpm test:e2e        # Playwright E2E tests
pnpm test:e2e:ui     # Playwright UI mode

Linting and formatting

pnpm lint            # ESLint
pnpm lint:fix        # ESLint with auto-fix
pnpm format          # Prettier

Database migrations

pnpm db:migrate           # run pending migrations
pnpm db:migrate:down      # roll back last migration
pnpm db:migrate:create    # create a new migration file

---

Key Features

• Real-time ingestion — streams Stellar ledger data via Horizon SSE with exponential backoff reconnection
• Circuit breaker — wraps all Horizon API calls; trips after 5 failures, resets after 5 minutes
• Idempotency — skips already-processed ledgers using a PostgreSQL tracking table
• Rate limiting — 3-tier API rate limiting (API key / JWT user / anonymous)
• GraphQL subscriptions — live dashboard updates over WebSocket
• Cursor-based pagination — Relay-style connections on all collection types
• Auth — JWT + bcrypt password hashing + API key support
• Observability — Prometheus metrics, structured logging (Winston/pino), slow query monitoring

---

Backup and Recovery

Automated PostgreSQL backups run via the postgres-backup compose service.

pnpm backup:run       # run a manual backup
pnpm backup:verify    # verify the latest backup
pnpm backup:health    # check backup health status

---

CI/CD

GitHub Actions workflows in .github/workflows/:

Workflow	Trigger
ci.yml	Push / PR to main or develop — runs unit tests then E2E tests
e2e-tests.yml	Dedicated E2E run
e2e-cross-browser.yml	Cross-browser E2E (Chrome, Firefox, Safari)

---

Project Structure

grantfox-analytics-dashboard/
├── packages/
│   ├── api/           # GraphQL API (Apollo Server, Express, Redis, WS)
│   ├── frontend/      # React dashboard (Vite, Tailwind, Zustand, Apollo)
│   ├── indexer/       # Data ingestion (Horizon SDK, circuit breaker, metrics)
│   ├── shared/        # Shared types, Zod schemas, constants
│   └── e2e/           # Playwright tests
├── scripts/
│   ├── backup/        # Backup shell scripts
│   └── database/      # Query analysis tools
├── docker-compose.yml
├── docker-compose.dev.yml
├── package.json       # Root monorepo scripts
└── pnpm-workspace.yaml

---

Contributing

Commits must follow Conventional Commits. The commitlint and husky hooks enforce this on every commit.

feat: add account filtering by balance range
fix: correct ledger sequence off-by-one in backfill
chore: update pnpm to 9.12.0