Crosswake User Flows And Jobs To Be Done

View Source

Crosswake is easiest to understand when you stop thinking about frameworks and start thinking about jobs.

Not "how do I get mobile features into Phoenix?"

Think instead:

  • How do I keep my main product Phoenix-owned on mobile without lying to myself?
  • How do I carve out one device-heavy corridor without turning the whole app native?
  • How do I support one meaningful offline workflow without pretending the whole app is local-first?

That is the real shape of Crosswake today.

If you want the profile matrix first, read guides/adopter_profiles.md. If you want the boundary details after this guide clicks, keep guides/bridge.md, guides/packs.md, guides/offline.md, guides/commerce.md, and guides/support_matrix.md nearby.

Why Crosswake Exists

Most Phoenix teams do not actually want a universal mobile UI framework.

They want something much more practical:

  • keep the product logic and most screens in Phoenix
  • use native ownership only where it is clearly the right tool
  • keep offline claims honest
  • ship mobile apps without inventing a generic plugin bus
  • know exactly what is supported and what is still their responsibility

Crosswake exists to make those decisions explicit per route.

That is why the core question in Crosswake is never "can mobile do this?"

It is:

Who should own this route?

The Core Mental Model

Think of Crosswake as a route-by-route ownership map.

Each important route in your app tends to fall into one of a few buckets:

  1. Phoenix should own it end to end.
  2. Phoenix should own the route, but the shell may help with one small native affordance.
  3. The route can degrade to cached read-only behavior.
  4. One route needs true local-first mutation and replay.
  5. One route needs native ownership because the device interaction loop is the product.

Crosswake gives you language and contracts for those buckets. It does not try to blur them together.

That is the memorable rule:

Crosswake does not "make mobile happen." It makes the crossing explicit.

Three Canonical Jobs

Crosswake currently proves three canonical jobs. If your app fits one of these, the library is speaking your language already.

Job 1: Keep The Main Product Phoenix-Owned On Mobile

This is the Phoenix SaaS Portal job.

Trigger

You have a normal SaaS product: dashboard, accounts, approvals, settings, maybe some deep links from email or notifications. Most of the product is already working well as LiveView. You do not want to rewrite it into a mobile UI stack just to get a credible app in the store.

Desired outcome

Keep the main product Phoenix-owned, put it inside an honest shell, and add one narrow native flourish where it actually helps.

What Crosswake is really buying you

  • a shell that activates routes from manifest truth instead of generic WebView vibes
  • explicit denial behavior when a route is unsupported
  • one bounded bridge seam for low-frequency native help
  • a support posture that tells you what is real and what is not

Happy-path flow

Imagine an approvals workflow in your SaaS.

  1. A manager opens the app from a deep link into an approval detail screen.
  2. The shell resolves that route from manifest truth before loading the runtime.
  3. The route stays :live_view; Phoenix still owns the data, rendering, and decision.
  4. The manager approves the request.
  5. The route optionally asks for haptics as a one-shot confirmation signal.
  6. The approval succeeds even if haptics does not.

The product authority never left Phoenix. The shell helped, but it did not take over.

Degraded path

  • If the shell cannot activate the route honestly, the user gets route unavailable.
  • If the shell cannot satisfy the native affordance, the Phoenix-owned action still completes and the route remains authoritative.

Why this boundary is right

This is the sweet spot for teams who mostly need "our Phoenix app, but mobile and credible." Crosswake helps you avoid overreacting and rebuilding product screens that already belong on the server.

Job 2: Move One Device-Heavy Corridor Native Without Contaminating The Rest

This is the Selective Native Flow job.

Trigger

Most of your app is still fine as Phoenix-owned UI, but one corridor is clearly a bad fit for a bounded web container. Common example: capture evidence for a claim, inspection, or field workflow.

Desired outcome

Promote exactly one route into explicit native ownership, keep the surrounding queue, detail, and review surfaces Phoenix-owned, and make the handoff obvious.

What Crosswake is really buying you

  • explicit :native_screen ownership instead of a blurry web fallback
  • route-local pack and transfer seams
  • fail-closed activation when the native prerequisites are missing
  • discipline against "while we're here, let's move five more flows native"

Happy-path flow

Imagine a claims app.

  1. An adjuster opens a Phoenix-owned claims queue.
  2. They choose one claim and move through Phoenix-owned detail and review screens.
  3. They tap Capture evidence.
  4. That route is declared :native_screen, so the shell owns the capture session.
  5. Media is staged locally.
  6. Phoenix regains control when the user returns to review and explicitly starts the upload preparation flow.

Only the capture corridor goes native. The rest of the product keeps the simpler, safer ownership model.

Degraded path

  • If the required pack is missing or incompatible, activation fails with pack_incompatible.
  • If native capture is required, Crosswake does not silently dump the user into a web upload fallback and pretend the experience is equivalent.

Why this boundary is right

Device-heavy loops have a way of spreading. Crosswake’s job here is not just to help you go native once. It is to stop that one native decision from infecting the rest of the app architecture.

Job 3: Keep One Meaningful Workflow Useful Offline Without Pretending The Whole App Is Local-First

This is the Local-First Study Flow job.

Trigger

You have one route where a user should keep making progress offline, but the rest of the app still lives comfortably in Phoenix and on the server.

Desired outcome

Support one real local-first workflow with journaling and replay, while keeping nearby read-only routes clearly different from local mutation authority.

What Crosswake is really buying you

  • a clear distinction between cached read-only routes and true offline islands
  • explicit journal and replay semantics
  • conflict visibility instead of silent overwrite stories
  • a narrow, believable offline claim

Happy-path flow

Imagine a study or training app.

  1. A learner opens a study session on a train with bad connectivity.
  2. The study session route is an :offline_island.
  3. Answers and progress are saved locally.
  4. Completed semantic actions are appended to a journal.
  5. A nearby history route can still show cached read-only data.
  6. When connectivity returns, replay runs explicitly and Phoenix becomes authoritative again after reconciliation.

This is not "the app works offline." It is "this route has a real local-first contract."

Degraded path

  • Replay may end in accepted, rejected, or conflict.
  • conflict requires attention is a feature, not a defect. It is Crosswake refusing to invent fake certainty.
  • There is no promise of broad background sync or magical app-wide offline state.

Why this boundary is right

Offline credibility comes from saying less and proving more. Crosswake would rather ship one honest offline island than market a vague sync fantasy.

Route-By-Route User Flows

When you adopt Crosswake, the real work is to classify your routes honestly.

Keep It :live_view

Use this when:

  • the route is mostly server truth and normal product interaction
  • mobile adds convenience, not ownership pressure
  • failure should look like ordinary Phoenix behavior, not native session recovery

Typical examples:

  • dashboard
  • account detail
  • settings
  • approval list
  • approval detail
  • billing history

Keep It Phoenix-Owned, Add One Bounded Capability

Use this when:

  • the route stays server-owned
  • the native interaction is one-shot and semantic
  • the shell is helping, not driving

Typical examples:

  • haptic confirmation after approval
  • share a generated link or export
  • read app info
  • inspect notification permission status before showing setup guidance

Use Cached Read-Only

Use this when:

  • stale content is acceptable
  • local mutation is not
  • the route should degrade, not fork into a local authority model

Typical examples:

  • study history
  • content library
  • read-only reference material

Use :offline_island

Use this when:

  • progress must continue offline
  • semantic mutations can be journaled
  • replay and conflict semantics are acceptable product behavior

Typical examples:

  • study session
  • training checklist with explicit replay

Use :native_screen

Use this when:

  • the device session loop is the product
  • permission choreography or capture fidelity matters
  • pretending the route is "just another bridge call" would be dishonest

Typical examples:

  • camera-driven evidence capture
  • future scanner or document scan corridors when they are truly native-first

What Crosswake Deliberately Does Not Do

Crosswake is not trying to be:

  • a universal shared UI system
  • a generic WebView wrapper
  • a plugin marketplace
  • a high-frequency client-state bridge
  • an app-wide offline engine
  • a billing engine

Those are not missing marketing bullets. They are deliberate thesis protection.

How To Decide If Your Flow Fits

Ask these in order:

  1. If mobile vanished, would Phoenix still be the obvious owner of this route?
  2. Is the native help one-shot and semantic, or is it the interaction loop itself?
  3. If offline matters, do I need cached read-only or true local mutation?
  4. If the route fails, do I want explicit denial, explicit conflict, or a native session surface?

If your answers cluster around:

  • mostly Phoenix, one narrow affordance: Crosswake already fits well
  • one device-heavy corridor: Crosswake already fits well
  • one honest offline workflow: Crosswake already fits well
  • broad plugin catalogs, constant native chatter, or app-wide sync magic: you are outside the current thesis

What Is Next

The next most natural jobs for Crosswake to deepen are:

  • commerce and paywall corridors
  • notification-driven re-entry flows
  • auth and account-security-sensitive mobile seams
  • richer operator truth and diagnostics

Those matter because they introduce new ownership decisions, new denial behavior, and new support obligations. They are more valuable than piling on minor capability families that do not change the route-ownership story.

For the deeper roadmap view of those gaps and their likely order, read the planning research memo maintained alongside the project’s milestone artifacts.