Reading the graph on demand

Everything until now was the write side — building and maintaining the graph. But a risk graph nobody can query is useless. This lesson is the read surface: how something asks "what's the risk of address 0xabc?" and gets an answer in milliseconds. The headline insight is an asymmetry: writes are hard and funnelled through one pod; reads are easy, cheap, and can be served by many — by design.

1 · An honest look: query-api is a scaffold (and that's a lesson)

The query-api binary (cmd/query-api/main.go) is the intended external read API. Reading the actual source, you find a production-grade HTTP service shell — but the graph endpoints aren't built yet:

// cmd/query-api/main.go
mux.Handle("GET /metrics", otelResult.MetricsHandler)
mux.HandleFunc("GET /healthz", ...)        // liveness
mux.HandleFunc("GET /readyz", ...)         // readiness
mux.HandleFunc("GET /api/v1/pipeline/status", ...)
// TODO: add graph query endpoints

What the scaffold teaches: the canonical HTTP service shape

Even as a shell, it's the template for every HTTP service here, and it's wired into the observability you learned in L11:

Source: cmd/query-api/main.go (otelhttp, metrics middleware, healthz/readyz, graceful shutdown, the TODO).

2 · So where are graph reads served today?

If query-api is a shell, the live read surfaces are:

3 · The deep part: the read discipline

Here's what actually matters and transfers everywhere. The graph is ~1.8M nodes / ~1.5 GiB. A read endpoint that loaded it, or scanned it, would die. Three disciplines keep reads cheap — and you've met all three:

① Never load the whole graph — look up only what you touch

NodeLookup exists precisely to avoid loading the full graph for the few hundred nodes a query actually needs:

// pkg/rules/node_lookup.go
// "serves per-id RiskNode reads … instead of loading the full graph
//  (1.8M nodes, ~1.5 GiB heap) … with just the nodes the rules
//  actually touch (typically a few hundred)."
func (nl *NodeLookup) Get(id) *risk.RiskNode { // per-id, TTL-cached; nil = doesn't exist }

This is L2's "anchor every query, no full scans" rule, embodied as a type.

② Reads are cheap because the work was done at write time

A read of "what's the risk of 0xabc?" does not compute risk — it fetches a pre-stamped property. The risk engine already computed node_risk_score, admin_risk_usd, etc. (L13) and wrote them onto the node. The read is a property lookup, not a calculation. The system pays the cost once, at write time, so every read is fast. (Live fields like balance read the Redis cache + RPC fallback — still no graph compute.)

③ Cache + TTL for the hot set

NodeLookup caches results with a TTL so a churn of repeatedly-read monitored nodes doesn't re-hit Memgraph every time, while the TTL still lets values refresh. Same caching instinct as the L7 RPC cache and the L8 Redis balance cache.

4 · The read/write asymmetry (the headline)

Check yourself

What you can now do

• Read a binary honestly — recognise a production HTTP scaffold with endpoints still TODO.
• Describe the canonical HTTP service shape here (otelhttp tracing, metrics middleware, healthz/readyz, graceful shutdown) and how it plugs into L11.
• Name the live read surfaces (admin-panel, rule-engine API, NodeLookup) and why auth lives on the read side.
• Explain the read discipline: never full-scan, pre-computed fields, TTL caches.
• Articulate the read/write (CQRS-flavoured) asymmetry and why it's deliberate.