Journeys Guide
Purpose: Narrative end-to-end walkthroughs of the moves a team makes inside Swifter — from "Setup is complete" through one shipped screen to wiring it to a live endpoint. Each journey is a worked example you can follow on your own engagement.
Reading time: ~3 minutes for the index · Audience: a person seeing Swifter for the first time · The journeys are deliberately written as concrete walkthroughs (one specific app, one specific screen) rather than as abstract rules. The rules live in the Delivery Guide; the what to do, in order lives here.
The three journeys
The journeys share a single worked example: a small CRM with a Customers list screen and a GET /api/customers endpoint. Reading them in order takes you from "Setup is complete" to "screen running on mock data" to "screen wired to a live backend".
| Journey | What you finish with | Typical duration |
|---|---|---|
| 1 — Setting up the Swifter Project | Project created, modules wired, backend guidelines reviewed, frontend knowledge caches generated, backlog synced, Preview confirmed working on a session branch | One session (the first session, end to end) |
| 2 — Frontend Screen Happy Path | One Page Work Item shipped end-to-end on mock data, merged to main | Two sessions (origin + development) for a normal page |
| 3 — FE-BE Integration Happy Path | The Page on mocks now consumes the live endpoint via a separate Integration WI | One session (the Integration WI) |
| Troubleshooting | A failure pattern diagnosed and recovered without recreating the Work Item | As needed |
Video guide
Prefer watching over reading? The Frontend Screen Video Guide — Component walks the same 18-step component flow as Journey 2 as short narrated clips — one clip per trigger, with a sentence or two on what to notice. No keyboard required.
How to read a journey
Each journey is structured the same way:
- A worked example — one specific app / screen / endpoint, named at the top of the page. Your engagement will have different names, but the steps are the same shape.
- The journey at a glance — a vertical diagram showing the sequence of moves.
- Step-by-step prose — what to click, what to expect on screen, the common-mistake callout per step.
- What "done" looks like — the exit signal that says you can move to the next journey.
A journey is not a list of rules. The five universal Work-Item authoring principles, the per-type templates, the agent-and-command sequences — those are rules and they live in the Delivery Guide. A journey takes those rules and walks them through a single concrete example so you can recognise the shape on your own work.
What journeys assume
Each journey assumes the prior journey is done. Journey 2 assumes Journey 1 has run; Journey 3 assumes Journey 2 has run. If you are dropping in mid-engagement, ensure:
- The project is set up (Journey 1's exit signals are all green).
- The Work Item you are about to run meets the readiness bar in Work-Item Composition.
- The project guidelines exist (see Project Guidelines) — backend guidelines are a hard prerequisite for any backend implementation Work Item; frontend caches are a hard prerequisite for
generate-component.
If any of those is missing, fix it first; no journey rescues a poorly-prepared workspace.
When something goes wrong
If the screen stalls, the Work Item flips to ABANDONED, or Preview fails — do not create a new attempt-named Work Item. Go to Troubleshooting, find the symptom in the cheat-sheet table, and apply the recovery. The most expensive anti-pattern observed in production is recreating Work Items in place of fixing the description or the routing.