# 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//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. | Surface | Path prefix | Folder | Routes | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------ | | **Customer** | `/`, `/tara`, `/arete`, `/veritas`, `/nyx`, `/nisaba`, `/metis`, `/sophia`, `/library`, `/explore`, `/activity`, `/messages`, `/profile`, `/billing`, `/welcome`, `/landing`, `/onboarding`, `/legal/*`, `/lilith*`, `/atelier*`, `/scene*`, `/share/*`, `/tenant/*`, `/system*`, `/status`, `/aaa-upgrade`, `/events`, `/d/*`, `/domains/*`, `/v2*`, `/v3/landing`, `/v6` | `customer/` | 193 | | **Studio** | `/studio/*`, `/egbe-studio` (V6), `/mawu-studio/*` (V7) | `studio/` | 493 | | **Operator** | `/operator/*` | `operator/` | 13 | | **Workspace** | `/(workspace)/*`, `/app/[surface]/*` | `workspace/` | 2 | 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`](./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/`](../ADMIN_WALKTHROUGH/README.md) — **exists** - `apps/oshun/tenant-admin` (institution admin, 15 routes) → [`../TENANT_ADMIN_WALKTHROUGH/`](../TENANT_ADMIN_WALKTHROUGH/README.md) — **partial** (`/identity` cockpit walked; remaining tenant-admin routes still need live verification) - `apps/oshun/mobile` (Expo / React Native, screen-based) → [`../MOBILE_WALKTHROUGH/`](../MOBILE_WALKTHROUGH/README.md) — **documented** (12 drafted screens) - `apps/oshun/telegram-miniapp` (Telegram WebApp, 2 routes) → [`../TELEGRAM_WALKTHROUGH/`](../TELEGRAM_WALKTHROUGH/README.md) — **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`](./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`](./matrix/routes.csv). ## Reading order If you're new to Oshun: start at [`shell/01-app-shell.md`](./shell/01-app-shell.md), then [`customer/02-home-discovery/home.md`](./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`](./journeys/README.md) 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`](../V1/features.md) - Architecture: [`V1/ARCHITECTURE.md`](../V1/ARCHITECTURE.md) - Execution backlog: [`V1/TODOS.md`](../V1/TODOS.md) - Code: `apps/oshun/web/src/app//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.