Data Access Architecture

This is the canonical read path for Sage Protocol clients.

Rule

CLI and SDK must not query subgraph GraphQL endpoints directly.

Use worker REST APIs as the client read interface.

Flow

Contracts -> Subgraph (indexing) -> Worker (cache + REST) -> CLI / SDK / Web / MCP

Why

• Keeps client behavior consistent across surfaces
• Centralizes caching and query normalization
• Reduces expensive direct RPC/subgraph fan-out from client tools

Environment

• Worker reads subgraph via SUBGRAPH_URL
• CLI/SDK should target worker base URLs (SAGE_API_URL, worker endpoints)

Operational Note

Subgraph lag can delay data visibility in worker responses. Handle this as eventual consistency, not as canonical state mismatch.