TECHNICAL CASE STUDY · Indexing · Platform integration
Graph Node infrastructure
Queryable data with observable freshness.
Implemented upstream integration and operational tooling
FROM THE IMPLEMENTATION
Measure when the indexed head first stopped moving
lag, newest_latest = _chain_progress(status)
if status.get("synced") and lag is not None and lag > HEAD_LAG_FLOOR:
return f"{subgraph} {lag} blocks behind chain head"
if newest_latest is None:
return None
last = _last_latest_blocks.get(subgraph)
if last is None or last[0] != newest_latest:
_last_latest_blocks[subgraph] = (newest_latest, now)
return None
if now - last[1] > HEAD_STALL_WINDOW:
return f"{subgraph} head not advancing"
return None
Selected contiguous excerpt from the freshness classifier. An unchanged head retains its original observation time, so polling cannot keep resetting the stall window. Excessive lag also overrides a subgraph’s synchronized flag.
THE ENGINEERING PROBLEM
What needed to work
An indexing platform can be reachable, report that it is synchronized, and still serve old data. I integrated upstream Graph Node with its storage and deployment dependencies, then built health checks that explain whether subgraphs are progressing rather than treating an open port as a complete operational answer.
Constraints and requirements
- Graph Node, PostgreSQL and IPFS have different startup and failure behavior. Operators need to distinguish a warming dependency, normal synchronization, a stalled index and a genuinely unavailable service without rewriting upstream Graph Node.
- Database data must survive container replacement. Configuration also needs a rollback path between a local database and the separately managed database service, while avoiding deployment definitions that depend on an inactive Compose profile.
ARCHITECTURE & DESIGN
How the system fits together
- Execution RPC
- Graph Node + subgraph mappings
- PostgreSQL + IPFS
- GraphQL queries
- Freshness + advancement health
Docker Compose describes Graph Node, IPFS, the HTTPS proxy and a Python health sidecar. The application consumes execution RPC data and exposes GraphQL query surfaces. Persistent volumes retain service data while source-controlled configuration is mounted read-only into the relevant containers.
The sidecar combines database and IPFS reachability with Graph Node’s indexing-status query. It reads subgraph health, synchronization state, indexed block and chain head, then returns a semantic status that the shared monitoring plane can interpret.
Decisions and tradeoffs
Measure freshness through both lag and advancement.
A synchronized flag can coexist with excessive chain lag. A subgraph still synchronizing can freeze without a flag change, so the indexed head needs a clock.
Tradeoff The sidecar keeps per-subgraph progress in memory. A restart grants a fresh observation window; status describes observed progress rather than assumed history.
Keep database convergence in the deployment workflow.
The legacy local database is profile-gated. The playbook orders its startup when selected, while the alternate path uses the configured database service.
Tradeoff Explicit ordering is more involved than a simple dependency declaration, but supports valid Compose configurations and preserves the retained-volume rollback.
PLANNING & EXECUTION
From requirements to working behavior
- I integrated shared Ansible deployment with pinned subgraph source, idempotent create/build/deploy behavior and persistent database storage. HTTPS query access, administration interfaces and monitoring access are configured as separate concerns.
- The health adapter maps connection resets, truncated responses and read timeouts into structured dependency failures. A failing dependency produces an explainable status instead of crashing the health handler and losing the operator’s diagnostic surface.
VALIDATION & RECOVERY
How the behavior is checked
- Maintained tests cover lag thresholds, frozen and advancing heads, string block-number parsing, missing progress fields, dependency resets and semantic HTTP mapping. The suite also exercises anonymous-report forwarding with and without configured authentication. Deployment verification remains separate from these source checks.
Implementation references
Repository-relative references identify the implementation behind this case study. Selected code excerpts are also available in the portfolio.
- tf-hetzner/projects/graph/docker-compose.yml
- tf-hetzner/projects/graph/health_sidecar.py
- tf-hetzner/projects/graph/test_health_sidecar.py
- tf-hetzner/projects/graph/README.md