Subgraph Best Practices

Core Model

A Subgraph Has Two Jobs

1. Maintain a small set of current-state entities that the app can query cheaply.
2. Record event/history entities only when the product needs auditability, timelines, or activity feeds.

That framing should drive almost every design choice.

If a field is needed to render the current app state, keep it on a mutable entity. If a record exists only because an event happened, make it an immutable event entity.

Optimize For Query Shape, Not Indexing Cleverness

The best subgraph is not the one with the fanciest mapping layer. It is the one whose schema matches the actual product queries.