Crosswake Adoption Guide: Flashcard Demo App Architecture

View Source

This guide details the architecture of the Flashcard Demo App and provides step-by-step instructions for adopting the Crosswake offline-sync architecture in your own projects.

For the definitive install sequence, see guides/install.md.

Architecture Overview

The demo app demonstrates the Crosswake.Offline island philosophy. It is built as a Language Learning / Flashcard app, intentionally chosen to rigorously stress-test offline scenarios and eventual consistency.

Key Components:

  1. Phoenix Host (Backend): Uses Ecto to manage the truth state of the application.
  2. Crosswake Native Shell (Frontend): standalone SPM/Maven dependencies injected into the iOS/Android apps.
  3. Sync Engine (Bridge): Intercepts mutations while offline and buffers them. Once the device reconnects, the Bridge replays the log (eventual consistency) and synchronizes with the Phoenix Host.

Adopting the Offline-Sync Architecture

To implement this architecture in your own app, follow these steps:

1. Integrate the Crosswake Shell

Generate the shell as a thin, host-owned wrapper that your team reviews and owns after scaffolding. Its native dependencies resolve from published registries — SwiftPM github.com/szTheory/crosswake-shell-core-ios for iOS and Maven Central io.github.sztheory:crosswake-shell-core-android for Android — rather than vendored or monorepo-local paths. The "eject trap" is eliminated by publishing the reusable core logic as package-manager dependencies, not by avoiding the generator.

2. Configure Offline Mutations

Define which user interactions (e.g., answering a flashcard) can be performed offline. Route these actions through the Crosswake bridge:

// Example: Recording an offline study session
Crosswake.mutate({
  type: 'study_card',
  payload: { cardId: '123', result: 'correct' },
  offlineCapable: true
});

3. Handle Sync Reconnection

Ensure your Phoenix host's endpoints can receive and validate batched offline payloads. The backend must enforce sync state validation post-reconnection to reject invalid operations (tampering mitigation).

When the client reconnects:

  1. The client transmits the offline mutation log.
  2. The Ecto sync endpoint processes the log.
  3. The client receives confirmation and updates its local state.

4. End-to-End Verification

Implement network-toggling E2E tests (like Playwright) in your CI/CD pipeline to simulate offline states and explicitly assert that your truth state is synchronized post-reconnect.