WALKTHROUGH — Oshun V1 PWA

A granular, checklist-driven inventory of every view and interaction in the Oshun V1 PWA (the app served from apps/oshun/web). Built so a reviewer, QA, designer, or new engineer can walk the surface end-to-end and verify that what ships matches what was specified.

What this is (and is not)#

• Is: A per-view checklist that names every interactive element, every state (loading / empty / populated / error / offline / gated), and every cross-surface flow that traverses the view. Grounded in the actual code at apps/oshun/web/src/app/<route>/page.tsx.
• Is not: A spec. V1/features.md is the feature map. V1/ARCHITECTURE.md is the runtime architecture. V1/TODOS.md is the execution backlog. This folder describes the surface that those documents produce — what a human actually clicks, swipes, types, hears, and reads.

Use this when you want to answer: "Does every view actually do what it's supposed to, in every state, with every input device, in every network condition?"

Surface map#

The V1 PWA serves four surfaces from a single Next.js app at apps/oshun/web. Each surface has its own walkthrough folder.

Totals are the live routes.csv tallies (701 routes overall: 692 in-v1 + 9 out-of-v1). The out-of-v1 set is /v2×4, /v3/landing, /v6 (customer) and /egbe-studio, /mawu-studio/*×2 (studio) — future V2/V3/V6/V7 surfaces that ship in the V1 build, documented for completeness. /egbe-studio and /mawu-studio/* are top-level routes that render ShellLayout active="studio", so they are counted under Studio and filed in studio/future/. Per-view file count and CSV row count match the app's page.tsx set exactly — see matrix/coverage.md for the per-domain breakdown and the audit-sweep history.

The separate apps each get their own top-level walkthrough folder (each is a distinct Next.js / Expo app with its own layout, middleware, auth, and IA — not part of apps/oshun/web):

• apps/oshun/admin (operator cockpit, 34 routes) → ../ADMIN_WALKTHROUGH/ — exists
• apps/oshun/tenant-admin (institution admin, 15 routes) → ../TENANT_ADMIN_WALKTHROUGH/ — partial (/identity cockpit walked; remaining tenant-admin routes still need live verification)
• apps/oshun/mobile (Expo / React Native, screen-based) → ../MOBILE_WALKTHROUGH/ — documented (12 drafted screens)
• apps/oshun/telegram-miniapp (Telegram WebApp, 2 routes) → ../TELEGRAM_WALKTHROUGH/ — documented (2 drafted routes)

This file (WALKTHROUGH/) covers the V1 PWA at apps/oshun/web only.

Folder layout#

WALKTHROUGH/
  README.md                # this file
  00-conventions.md        # checklist syntax, status legend, file template
  shell/                   # global chrome — applies to every view
    01-app-shell.md        # root layout, header, footer, theme, breakpoints
    02-routing-layouts.md  # route groups, error boundaries, suspense
    03-pwa-behavior.md     # manifest, service worker, install, offline, sync
    04-auth-session.md     # sign-in, refresh, gates, sign-out
    05-notifications.md    # toasts, push, in-app feed
    06-keyboard-a11y.md    # skip links, shortcuts, focus, SR announcements
    07-trust-safety.md     # flag button, crisis cascade, /profile/safety audit
    08-telemetry-analytics.md  # event taxonomy, transports, observability
    09-i18n-locale-time.md     # locale, RTL, datetime, timezone, hreflang
    10-feature-flags-experimentation.md  # flags, experiments, runtime config
    11-design-system-tokens.md           # Lilith tokens, primitives, shells
    12-overlays-and-panels.md            # command palette, assistant, dialogs
    13-domain-launch-runtime.md          # switcher, startup gate, degradation
    14-performance-web-vitals.md         # budgets, lighthouse, web vitals
  customer/                # customer-facing routes
    00-public/             # /landing, /welcome, /legal/*, /v2*, /v3*, /v6 (out-of-v1)
    01-onboarding/         # /onboarding/*
    02-home-discovery/     # /, /explore, /search, /library, /activity, /messages, /switcher
    03-tara/  04-arete/  05-veritas/  06-nyx/  07-nisaba/  08-metis/
    09-account/            # /profile/*, /billing/*
    10-lilith/             # /lilith, /lilith-studio/*
    11-atelier/            # /atelier/*
    12-scene/              # /scene/*
    13-system/             # /system/*, /status, /aaa-upgrade
    14-sophia/             # /sophia — grounded-only answer surface
  studio/                  # /studio/* — creator/editor/scholar workspace
    authoring/  generation/  governance/  operations/  design/
    collaboration/  domain-bridges/
    future/                # out-of-v1 studio surfaces: /egbe-studio (V6), /mawu-studio/* (V7)
  operator/                # /operator/* — admin product
  workspace/               # /(workspace)/*, /app/[surface]/*
  journeys/                # end-to-end multi-view flows
  matrix/
    routes.csv             # full V1 route inventory with status
    coverage.md            # narrative of what's done, stub, or deferred

How to read a per-view file#

Every per-view file follows the template in 00-conventions.md. It opens with a header (route, surface, domain, auth, source), then sections for purpose, entry points, layout regions, states, interactions, data & contracts, cross-references, and open questions. Every line that starts - [ ] is a verifiable check.

Status of any single file is one of:

• stub — file exists with header only, content not yet written
• drafted — content written from source evidence but not yet verified against the running app
• walked — direct runtime evidence (manual or automated) verifies the reachable checks, with the method and date recorded
• stale — code drifted since the last walk; needs re-verification

Status is tracked in matrix/routes.csv.

Reading order#

If you're new to Oshun: start at shell/01-app-shell.md, then customer/02-home-discovery/home.md for the home shell, then walk into the domain you own.

If you're reviewing a specific change: open matrix/routes.csv, filter by the route prefix you touched, walk only those files.

If you're testing for launch: walk the journey index first — it catches the cross-view bugs the per-view checklists miss — then sweep the per-view files for any state you haven't seen.

Source of truth#

• Feature scope: V1/features.md
• Architecture: V1/ARCHITECTURE.md
• Execution backlog: V1/TODOS.md
• Code: apps/oshun/web/src/app/<route>/page.tsx

If a walkthrough check contradicts one of those, the source of truth wins and the walkthrough is wrong — file an issue and fix the check.