Architecture guide

Glacier is small on purpose. Four components, each with one job, connected by narrow interfaces.

The four pieces

• Predictor — watches access events and maintains the model of what's likely to be needed next. It emits warm decisions and nothing else; it never touches data directly.
• Store — the warm set. Holds entries with their ttl and tags, handles eviction, and answers get/has. Pluggable: in-memory by default, or back it with Redis or a KV store.
• Edge layer — present only when edge: true. Runs the predictor and store per region and propagates invalidations between nodes.
• Adapters — translate a framework's request lifecycle into the events the predictor consumes and the fetches the store fills.

Request flow

1. A request arrives; the active adapter records an access event.
2. The store answers from the warm set if it can (a hit).
3. On a miss, the underlying fetch runs and the result is stored.
4. Asynchronously, the predictor folds the event into its model and may warm related keys.

The fetch path never waits on the predictor — prediction is always off the critical path.

Why the source of truth stays out

The store is deliberately not authoritative. Every entry is reconstructable from the origin, so a cold or wrong cache degrades to "no cache," never to "wrong answer." That single constraint is what makes Glacier safe to drop into an existing app.

Read the Design principles for the rules these pieces are built to honor.