Home · Get started · Design · Architecture · Testing · Deployment · Watch & reflection · Weekly contribution

Architecture

Offshift is a Next.js application with a watch preview, daily reflection calendar, and earlier phone/3D views. The original scenario uses a shared Zustand store. Watch readings, new reflections and recovery blocks use a separate browser-only store and are excluded from the shared state and assistant context.

flowchart LR
    W[Watch preview /watch] <--> R[Private browser store]
    D[Daily reflection /calendar] <--> R
    D --> S[Shared scenario store]
    R --> B[LocalStorage only]
    P[Phone view /] --> S
    C[Calendar /calendar] --> S
    S --> L[Time helpers + care checks]
    S <--> Y[Sync provider]
    Y <--> A[State API /api/state]
    A --> F[Process memory + local JSON]
    C --> V[Assistant API /api/assistant]
    V --> O[Scripted fallback]
    V --> H[Optional hosted language model]
    C --> M[Local MediaPipe hand tracking]

The daily view is the default calendar. The optional board is loaded only for ?view=3d or ?immersive=1. Watch & reflection describes the import boundary and remaining device integration.

Where to work

Area	Source	Responsibility
Watch data	watch.ts	Import validation, provenance, timestamp/date matching and recovery previews.
Private watch store	watch-store.ts	Browser-only readings, reflections, confirmed recovery blocks and deletion.
Domain types	types.ts	Shifts, offers, plans, messages and settings.
Scenario	scenario.ts	Fixed clock and fictional demonstration data.
Time calculations	logic.ts	Paid time, income, overlaps, travel buffers and rest windows.
Care checks	checks.ts	Body / Week / Money, alternatives and reply drafts.
Store	store.ts	State, persistence, offer responses and reset actions.
Cross-device sync	sync.tsx	Debounced writes and one-second polling.
Board	Calendar components	Three.js scene, immersive controls and assistant UI.
Gestures	gestures.ts	Pure gesture-state engine tested separately from the camera.
Hand input	hands.ts	MediaPipe landmarks and browser camera processing.

State and sync

The store separates scenario data from UI state such as which app or sheet is open. pickData selects the shared data. Browser persistence uses localStorage when available and falls back to memory when it is unavailable.

Changes queue a write after 150 ms. Other clients poll /api/state roughly once a second. The route tracks a version and client ID, keeps data in process memory, and attempts to write a JSON file. This is prototype synchronization: there is no transactional merge, authentication or per-user isolation.

Time model

The scenario uses weekday labels and 24-hour clock strings, rather than dated, timezone-aware events. An end clock earlier than the start means the next day. Equal clocks mean an empty interval. Touching endpoints do not overlap.

shiftImpact compares dated intervals within the scenario week and accounts for adjacent-day events. When a Sunday shift crosses midnight, Monday commitments are treated as the next weekly occurrence. The calendar rendering and every higher-level narrative are not a complete overnight scheduling system; the regression change specifically covers the shared time calculations.

Assistant and camera

/api/assistant uses an optional hosted language model when server credentials are present and falls back to scripted responses. It returns speech text and structured actions; the client applies those actions to the scenario. This does not connect to a real employer messaging service.

Hand and face-presence processing runs in the browser with locally served model files. Presence detection does not identify a person. The optional hosted assistant is a separate data path and receives scenario context.

Next: Test behaviour before changing it.