Concepts

Snapshot

A snapshot is the public JSON object your portfolio renders. It contains ordered cards and per-source state.

Cards

Cards are normalized display objects. They do not expose raw provider payloads.

The v1 card kinds are:

• building
• playing
• listening

Sources

Sources know how to fetch or record activity and return one normalized card. The built-in sources are GitHub, WakaTime, Last.fm, and played events.

Store

The store is a tiny async key-value interface used for snapshot cache and played event persistence. The package passes configured TTLs through this interface; the application's store adapter applies the equivalent expiry in its backend. Snapshot cache entries also carry an expiresAt timestamp so they stay fresh even when a backend cannot enforce TTLs.

Fallbacks and stale data

Fallbacks keep your page populated when a source is empty. Last-good stale data keeps your page stable when a provider temporarily fails. Only fresh source cards update recovery data. Recovery entries are stored and expired per kind. Other outcomes leave those entries untouched, but the current snapshot still reflects the source outcome.