3.7 KiB
Architecture
Platform Scope
The accepted V1 is iOS-only. Existing Android adapter code is retained as a future starting point, but Android behavior, builds, accessibility, and release work are outside the current delivery scope.
Baseline
The mobile architecture follows the parts of KnoKno that have already proven useful on physical iOS and Android devices:
- React Native bare workflow and real native projects;
- typed native-stack navigation;
- feature-owned modules rather than a screen dump;
- Zustand for client state and AsyncStorage for durable local state;
- service boundaries around native capabilities;
- bilingual strings from the first implementation;
- Jest, Testing Library, TypeScript, and lint gates;
- explicit bootstrap, offline, error, and recovery states.
KnoKno's AI backend, auth complexity, rollout flags, RevenueCat, and analytics are not copied by default. They are added only where this product's accepted flows require them.
Runtime Layers
App bootstrap and navigation
-> feature screens and components
-> domain commands and selectors
-> persisted Zustand store
-> device service interfaces
-> Apple HealthKit provider
-> Android Health Connect provider
-> app timers and manual records
-> notifications, sharing, and haptics
The UI never awards growth directly. It records or imports a LifeEvent; the
domain engine normalizes, deduplicates, corrects, and derives the visible
relationship and habitat state.
Durable Entities
| Entity | Purpose |
|---|---|
Companion |
Permanent identity, name, species, temperament, palette, birth mark |
LifeSignal |
Configured automatic, timer, quick-log, or custom source |
LifeEvent |
Stable fact with source, device, time, local day, status, and idempotency key |
Correction |
Ignore one event or disable a source without rewriting history |
SharedDay |
At most one relationship day derived from accepted events |
DirectionState |
Activity, Calm, Focus, and Vitality stages and visible outputs |
Journey |
Relationship stage, nodes, and consequence-bearing choices |
Discovery |
Clue, reveal, placement, reuse, and provenance state |
Habitat |
Slots, placed objects, unlocked hotspots, markings, and region state |
Memory |
Template-safe chronicle derived only from accepted events and choices |
Preferences |
Motion, haptics, notifications, privacy, and language |
Every persisted root contains a schema version. Migrations are deterministic, tested, and never infer events the user did not record.
Event Pipeline
native sample / timer / one-tap / custom action
-> normalize timestamp, source, device, local day, and idempotency key
-> deduplicate
-> store immutable LifeEvent
-> derive no more than one direction mark per direction per day
-> derive no more than one SharedDay per day
-> enqueue one companion response
-> reveal the corresponding durable world change
Corrections invalidate downstream derived facts during a deterministic rebuild. Raw HealthKit and Health Connect samples remain on device; only the minimum derived facts belong in the app store.
Animation
Each species owns frame sequences. Temperament changes delay, distance, path, and sequence choice. Palette, birth mark, growth marking, held object, and environment result are separate layers. The runtime always supports a static fallback and a reduced-motion sequence of at most three ordered key poses.
Offline And Recovery
The primary companion, events, corrections, discoveries, placements, memories, and preferences work without a network. Provider refresh failures do not block manual actions or companion access. The app persists timer start time so a backgrounded or killed app can restore the correct elapsed state.