purewhiter--mobilegym/docs/platform/app/data-layering.md

App Data Layering

This page is the app-author entry point for deciding what belongs in constants.ts, data/defaults.json, world data files, and runtime state. The full state model is in ../state/model.md.

Files

File	Owns
constants.ts	Static app structure: tabs, service grids, feature flags, layout constants.
data/defaults.json	Replaceable initial user/content/settings state.
data/index.ts	Merge point that exports <APPNAME>_CONFIG.
state.ts / context store	Mutable runtime overlay exposed through __SIM__.getState().
Large data files / loaders	Read-mostly world data that should not bloat snapshots.

Constants vs. Defaults

Use constants.ts for app-inherent structure:

• Tab definitions.
• Fixed service catalogs.
• Feature flags.
• Layout constants.

Use data/defaults.json for replaceable user/runtime seed data:

• Current user profile.
• Messages, posts, bills, history.
• User settings.
• User-configurable home layout or ordering.

Do not put raw Lucide icon names in either file; data-driven icon names must use app Ic* aliases.

World Data vs. Runtime Overlay

Layer	Example	Snapshot behavior
World data	Products, posts, songs, map places, stations.	Usually outside __SIM__.getState(); loaded by app helpers.
Runtime overlay	Current user, drafts, likes, settings, sent messages, per-entity overrides.	Included under apps.<appId> and used by state-mode judges.

Views compose both layers at render time. Store semantic fields, not display strings that tests later need to parse.

Bench-Facing Accessors

If bench tasks need to judge a view, provide stable accessors or shared helper logic so the app and task code resolve the same user-visible state. Do not duplicate display derivation in a way that can drift.

Related Docs

• Full state model → ../state/model.md
• App state snapshots → ../state/app-state.md
• Bench snapshots and diffs → ../state/bench-snapshots.md