Guided walkthroughs

A guided walkthrough is an in-app product tour — a sequence of spotlight tooltips that introduces a first-time agent to the portal. It exists in the broker and sales-man apps only (never the shopper or analytics apps). The tour is built on react-joyride and is driven by a shared component in @orascom/common-components.

Whether the tour runs is decided by two gates that work together:

• A client-side flag in the browser — localStorage key WALKTHROUGH_LOCALSTORAGE_KEY (literal value 'walkthroughStep', frontend/libs/common-components/src/lib/walkThrough/Constants.tsx:1). This flag doubles as a resume pointer: it stores the current step number ('1', '2', …), not just a boolean.
• A durable per-user status on the backend — the is_walkthrough_done boolean column. Once it is true, the flag is never re-seeded on future logins, so the tour never shows again.

The whole trip, in one diagram

sequenceDiagram
actor U as Agent (Broker / Sales-Man)
participant SPA as Agent SPA
participant LS as localStorage
participant JR as Joyride tour
participant API as Backend (Laravel)
participant DB as users / sales_team
U->>SPA: First login
SPA->>API: GET /user (userDataLoader)
API-->>SPA: user.is_walkthrough_done = false
SPA->>LS: setItem walkthroughStep = 1
Note over SPA,JR: tour runs only while the flag is truthy
JR->>U: Step 1 Welcome (anchored to page body)
loop each step
  JR->>LS: setItem walkthroughStep = stepIndex + 1
  JR->>SPA: navigate to the step route
end
U->>JR: Finish or Skip
JR->>LS: removeItem walkthroughStep
JR->>SPA: set is_walkthrough_done true in user context
JR->>API: PUT user/complete-walkthrough (fire-and-forget)
API->>DB: is_walkthrough_done = true
JR->>SPA: navigate home (replace)
Note over API,DB: next login returns done = true so the flag is never re-seeded

Guided walkthrough — first-login seed, tour run, completion write-back (verified)

How the gating actually works

1. First login seeds the flag — both apps run a userDataLoader on the authenticated route. It fetches GET /user, then: if user.is_walkthrough_done is already true it removes the flag; otherwise, if no flag exists yet, it sets WALKTHROUGH_LOCALSTORAGE_KEY to '1' (broker frontend/apps/orascom-broker-app/src/api/user-data-loader.ts:24-28; sales-man frontend/apps/orascom-sales-man-app/src/api/user-data-loader.ts:33-37). So the backend status is what decides whether a fresh browser gets seeded at all.

2. The tour only runs while the flag is truthy — the shared WalkthroughComponent initialises its currentStep from Number(localStorage.getItem(WALKTHROUGH_LOCALSTORAGE_KEY)) || undefined (frontend/libs/common-components/src/lib/walkThrough/walkthrough-component/walkthrough-component.tsx:60-62) and gates the Joyride with run={isJoyrideRunning && run && !!currentStep} (:144). No flag ⇒ currentStep is undefined ⇒ the tour does not start. It is mounted via createPortal from each app’s main-layout (broker .../layouts/main-layout/main-layout.tsx:87-97; sales-man :102-112).

3. Each step persists the pointer and navigates — while status === 'running', the callback writes the new step number back to localStorage (walkthrough-component.tsx:91-102) and navigates to that step’s data.route (:104-120). Because the pointer is stored, a mid-tour reload resumes at the saved step rather than restarting. The step list lives in each app’s utils/walkthroughSteps.ts / utils/walkThroughSteps.ts (e.g. broker brokerSteps, frontend/apps/orascom-broker-app/src/utils/walkthroughSteps.ts:9), and each spotlight targets a WALKTHROUGH_TARGETS_IDS anchor (Constants.tsx:3).

4. Direct-URL access to a tour page is blocked when the flag is unset — the dedicated walkthrough routes redirect home unless the flag is present. Broker: hitting WALKTHROUGH_DEAL_DETAILS or WALKTHROUGH_UNIT without the flag ⇒ Navigate to the dashboard (frontend/apps/orascom-broker-app/src/components/protected-routes/protected-routes.tsx:76-82). Sales-man: WALKTHROUGH_UNIT or WALKTHROUGH_PIPELINE without the flag ⇒ Navigate to the overview (frontend/apps/orascom-sales-man-app/src/components/protected-routes/protected-routes.tsx:104-112). You cannot deep-link into a tour page.

5. Finish or Skip clears the flag and writes the backend status — on status === 'finished' or 'skipped' the callback runs, in order: removeItem(WALKTHROUGH_LOCALSTORAGE_KEY) → updateUserStateOnFinish?.() (sets is_walkthrough_done: true on the in-memory user context) → updateWalkthroughStatus?.() (the backend call) → navigate('/', { replace: true }) (walkthrough-component.tsx:72-78). The backend call is not awaited — it is fire-and-forget (see Gotchas).

6. The backend call marks the user done — updateWalkthroughStatus() issues PUT /user/complete-walkthrough (endpoint updateUserWalkthroughStatus, broker frontend/apps/orascom-broker-app/src/api/endpoints.ts:219-222; sales-man frontend/apps/orascom-sales-man-app/src/api/endpoints.ts:121-124; broker call frontend/apps/orascom-broker-app/src/api/user.ts:42-47). Server-side the route sits inside the auth:sanctum group (backend/routes/api.php:26-29, route at :28) and hits UserController@completeWalkThrough, which flips the column only if it is still false and returns respondSuccess() (backend/app/Http/Controllers/Api/Auth/UserController.php:52-61). There is no dedicated Action — the one-line update is inline in the thin controller. The column is is_walkthrough_done (boolean, default false), added by two migrations: users for brokers (backend/database/migrations/2025_03_03_113729_add_column_is_walkthrough_done_to_users_table.php:14) and sales_team for sales-men (backend/database/migrations/2025_03_03_114302_add_column_is_walkthrough_done_to_sales_team_table.php:14). It is $fillable on both models (backend/app/Models/User.php:39, backend/app/Models/SalesMan.php:25) and returned by UserResource (backend/app/Http/Resources/UserResource.php:30) so GET /user can report it back on the next login.

The two gates have different jobs

The localStorage flag is the session-level runner + resume pointer — it decides whether the tour runs right now and where it left off. The is_walkthrough_done column is the durable memory — it decides whether userDataLoader ever re-seeds the flag again. Clearing localStorage re-triggers the tour on the next load only if the backend still has is_walkthrough_done = false; if the completion write succeeded, the loader removes the flag every time and the tour stays gone.

The walkthrough routes

Each dedicated tour page renders hardcoded static dummy data (staticUnit / staticLead / staticPipeline) rather than fetching, so it loads instantly and is safe to render without live records. The ids embedded in the paths (1/0/3, pipelines/1) are placeholders, not real records.

App	Route (ROUTES_MAPPER)	Component	Renders
Broker	/unit-details/walkthrough (WALKTHROUGH_UNIT, routesMapper.ts:52)	pages/walkthroughUnit/WalkthroughUnit.tsx (route routes.tsx:161)	Static unit-details layout — gallery, info, floor plan, payment plan, specs
Broker	/deal-details/walkthrough/1/0/3 (WALKTHROUGH_DEAL_DETAILS, routesMapper.ts:51)	pages/walkthroughDealDetails/WalkthroughDealDetails.tsx (route routes.tsx:283)	Static deal-details with breadcrumbs, meetings, invoice, lead-info card
Sales-Man	/unit-details/walkthrough (WALKTHROUGH_UNIT, routesMapper.ts:43)	pages/walkthroughUnit/WalkthroughUnit.tsx (route routes.tsx:267)	Static unit-details layout (no payment-plan block)
Sales-Man	/leads/walkthrough/pipelines/1 (WALKTHROUGH_PIPELINE, routesMapper.ts:44)	pages/walkthroughPipeline/WalkthroughPipeline.tsx (route routes.tsx:275)	Static pipeline-details via PipelineDetailsStatic

The rest of the tour steps point at real pages (dashboard, destination details, primary units, new-deal, analytics) — the dedicated static pages above exist only for the steps where showing a live, fetched record would be slow or require data the new agent does not have yet. Those tour-driving routes plus NEW_DEAL are also listed in each layout’s WALKTHROUGH_ROUTES array (broker main-layout.tsx:24-28; sales-man :30-34) so the tour is allowed to run over them without waiting for their queries to settle.

Gotchas

The completion write is fire-and-forget — a failure re-shows the tour

In the finish/skip handler, updateWalkthroughStatus?.() is called without await and its result is ignored, then the app navigates home immediately (walkthrough-component.tsx:76-77). If that PUT /user/complete-walkthrough fails (network, 401, wrong host), is_walkthrough_done stays false server-side. The in-memory context is updated so the tour is quiet for the rest of the session, but on the next login userDataLoader sees is_walkthrough_done = false and re-seeds the flag — the agent is walked through the tour again. There is no retry.

The sales-man completion call targets the BROKER endpoint env

The sales-man app’s updateWalkthroughStatus() builds its URL from NX__BROKER_API_ENDPOINT, not NX__SALESMAN_API_ENDPOINT (frontend/apps/orascom-sales-man-app/src/api/user.ts:31-36) — every other method in that same file uses the sales-man env. If the two env values differ (different host or prefix per environment) the sales-man completion PUT goes to the wrong backend and can 401/404, so a sales-man’s is_walkthrough_done may never get set and the tour keeps reappearing. This is a verified bug worth filing on the KT tracker.

The flag key is shared by name across both apps

Both apps import the same constant, so the key is literally 'walkthroughStep' in each. They do not collide because broker and sales-man are separate deployments on separate origins — localStorage is per-origin. Just be aware the key is not persona-namespaced the way the token keys are (NX_BROKER_ACCESS_TOKEN_KEY etc.), so on a shared dev host that serves both apps from one origin they would share one flag.

Sales-man deal-details reads the flag once at module load

In the sales-man deal-details page, walkthroughLocalstorageCheck is a module-level localStorage.getItem(WALKTHROUGH_LOCALSTORAGE_KEY) captured at import time (frontend/apps/orascom-sales-man-app/src/pages/deal-details/deal-details-page.tsx:22-24). It is used to skip the loader spinner and to render DealDetails without the UserPipelineProvider wrapper while the tour is active (:44, :66-69). Because it is read once (not reactively), its value reflects whatever the flag was when the module first loaded — a subtlety to keep in mind when debugging deal-details behaviour during a tour.

While the tour pauses, a transparent overlay blocks the app

Between steps that navigate to a real (still-fetching) page, shouldWalkthroughRun goes false and a full-screen TempWalkthroughOverlay is shown while the flag is set (broker main-layout.tsx:83-86; sales-man :98-101). It is transparent and aria-busy, and it swallows key events so the agent cannot interact with the half-loaded page until the next step is ready. If a tour ever appears “frozen,” this overlay plus a step whose target element never loads is the place to look.

Where to go next

Broker deal lifecycleThe real deal-details and pipeline screens the tour's static walkthrough pages stand in for.

Sales-man pipelineThe live pipeline screen behind the sales-man WALKTHROUGH_PIPELINE static page.

PersonasWho sees a tour (Broker and Sales-Man) and how each authenticates — the tour never runs for shoppers.

KT tracker (known issues & unknowns)Where the sales-man wrong-endpoint bug and the fire-and-forget completion write are logged.