# Webapp-next Refactor Baseline Audit

This note captures the baseline before the phased refactor. It defines current risks,
duplication hotspots, and expected behavior that must not regress.

## 1) Screens and boundaries

- Home route orchestration: `webapp-next/src/app/page.tsx`
  - Chooses among `AccessDeniedScreen`, `CurrentDutyView`, `CalendarPage`.
  - Controls app visibility via `appContentReady`.
- Admin route orchestration: `webapp-next/src/app/admin/page.tsx`
  - Thin route, but still owns shell duplication and content-ready signaling.
- Calendar composition root: `webapp-next/src/components/CalendarPage.tsx`
  - Combines sticky layout, swipe, month loading, auto-refresh, settings button.
- Current duty feature root: `webapp-next/src/components/current-duty/CurrentDutyView.tsx`
  - Combines data loading, error/access states, back button, and close action.
- Admin feature state root: `webapp-next/src/components/admin/useAdminPage.ts`
  - Combines SDK button handling, admin access, users/duties loading, sheet state,
    mutation and infinite scroll concerns.

## 2) Telegram integration touchpoints

- SDK/provider bootstrap:
  - `webapp-next/src/components/providers/TelegramProvider.tsx`
  - `webapp-next/src/components/ReadyGate.tsx`
  - `webapp-next/src/lib/telegram-ready.ts`
- Direct control usage in feature code:
  - `backButton` in `CurrentDutyView` and `useAdminPage`
  - `settingsButton` in `CalendarPage`
  - `closeMiniApp` in `CurrentDutyView`
- Haptics in feature-level handlers:
  - `webapp-next/src/lib/telegram-haptic.ts`

Risk: platform behavior is spread across feature components instead of a narrow
platform boundary.

## 3) Layout and shell duplication

Repeated outer wrappers appear across route and state screens:
- `content-safe min-h-[var(--tg-viewport-stable-height,100vh)] bg-background`
- `mx-auto flex w-full max-w-[var(--max-width-app)] flex-col`

Known locations:
- `webapp-next/src/app/page.tsx`
- `webapp-next/src/app/admin/page.tsx`
- `webapp-next/src/components/CalendarPage.tsx`
- `webapp-next/src/components/states/FullScreenStateShell.tsx`
- `webapp-next/src/app/not-found.tsx`
- `webapp-next/src/app/global-error.tsx`

Risk: future safe-area or viewport fixes require multi-file edits.

## 4) Readiness and lifecycle coupling

`appContentReady` is set by multiple screens/routes:
- `page.tsx`
- `admin/page.tsx`
- `CalendarPage.tsx`
- `CurrentDutyView.tsx`

`ReadyGate` is route-agnostic, but signaling is currently ad hoc.
Risk: race conditions or deadlock-like "hidden app" scenarios when screen states
change in future refactors.

## 5) Async/data-loading duplication

Repeated manual patterns (abort, retries, state machine):
- `webapp-next/src/hooks/use-month-data.ts`
- `webapp-next/src/components/current-duty/CurrentDutyView.tsx`
- `webapp-next/src/components/admin/useAdminPage.ts`

Risk: inconsistent retry/access-denied behavior and difficult maintenance.

## 6) Store mixing concerns

`webapp-next/src/store/app-store.ts` currently mixes:
- session/platform concerns (`lang`, `appContentReady`, `isAdmin`)
- calendar/domain concerns (`currentMonth`, `pendingMonth`, duties/events)
- view concerns (`currentView`, `selectedDay`, `error`, `accessDenied`)

Risk: high coupling and larger blast radius for otherwise local changes.

## 7) i18n/a11y gaps to close

- Hardcoded grid label in `CalendarGrid`: `aria-label="Calendar"`.
- Hardcoded sr-only close text in shared `Sheet`: `"Close"`.
- Mixed language access strategy (`useTranslation()` vs `getLang()/translate()`),
  valid for bootstrap/error boundary, but not explicitly codified in one place.

## 8) Telegram Mini Apps compliance checklist (baseline)

Already implemented well:
- Dynamic theme + runtime sync.
- Safe-area/content-safe-area usage via CSS vars and layout classes.
- `ready()` gate and Telegram loader handoff.
- Android low-performance class handling.

Needs explicit policy/consistency:
- Vertical swipes policy for gesture-heavy screens.
- Closing confirmation policy for stateful admin flows.
- Main/Secondary button usage policy for primary actions.
- Terminology alignment with current official docs:
  `safeAreaInset`, `contentSafeAreaInset`, fullscreen events.

## 9) Expected behavior (non-regression)

- `/`:
  - Shows access denied screen if not allowed.
  - Opens current-duty view for `startParam=duty`.
  - Otherwise opens calendar.
- `/admin`:
  - Denies non-admin users.
  - Loads users and duties for selected admin month.
  - Allows reassignment with visible feedback.
- Error/fallback states:
  - `not-found` and global error remain full-screen and theme-safe.
- Telegram UX:
  - Back/settings controls remain functional in Telegram context.
  - Ready handoff happens when first useful screen is visible.