jobtrackingapp/docs/redesign/audit/README.md

# Phase 1 — Frontend audit

Date: 2026-09-09. Source checkpoint: `97fce89c002fe86e737ca7387170321d464b80d7` (application changes through `0954876`; subsequent commits contain the brief and CI prerequisite corrections). Audit branch: `codex/ui-redesign-audit`. Test-only packaging correction `23cc250` leaves the frontend census unchanged; its fresh 22 PDF and 915 broader backend passes are recorded in the test assessment.

**Phase 1 source audit complete; redesign implementation has not started.** The repository already implements much of the proposed workflow. Retain its MUI/React foundation and domain contracts, improve shared semantics, then migrate representative screens in small steps. A replacement frontend framework or component library is not justified by the observed problems.

This is a source and regression-evidence audit, not a new visual usability study, production certification, or execution of security ticket B07. The existing security queue still governs unresolved integrity/recovery work. F04 remains open. A pushed revision is not proof of a successful deployment; see [release evidence](../../audits/2026-09-07/validation/b06-completion.md#authorized-release-attempt-and-ci-prerequisite-correction).

Release status, 2026-09-10: main `27657f3` is pushed. Run 743 passed 916 backend and 298 frontend tests, lint, audits and production builds, but the browser gate failed with a worker SIGSEGV and subsequent browser-closed errors; deployment was skipped. Further release attempts await runner diagnostics. The live endpoint still reports version 299. This does not block delivering the Phase 1 findings, but it does block claiming a verified live checkpoint for subsequent work.

## Deliverables and method

| Handoff requirement | Evidence |
|---|---|
| Architecture, styling, state | This document |
| Every declared route/page | [Route map](ROUTE_MAP.md): 31 concrete route patterns, including two redirect aliases; 29 page patterns |
| Existing user functionality | [Preservation ledger](FUNCTIONALITY_INVENTORY.md), including nested screens and non-navigation entry points |
| Components | [All production TSX modules](COMPONENT_INVENTORY.md), shared responsibility map below |
| Tests and gaps | [Test assessment](TEST_INVENTORY.md), [test-file census](TEST_FILES.md) |
| API integration | [Contract map](API_AND_IDENTITY.md), [266 call expressions](API_CALL_SITES.md) |
| Auth, authorization, storage | [Identity and storage boundaries](API_AND_IDENTITY.md) |
| Localisation, mobile, accessibility | Assessment below and [regression risks](RISKS_AND_MIGRATION.md) |
| Migration and decisions | [Proposed sequence and gates](RISKS_AND_MIGRATION.md) |

Read the ten documents required by [ASTRA_HANDOFF](../ASTRA_HANDOFF.md), then traced route elements, their local import graph, event handlers, API wrappers, server controllers/services, security middleware, test configuration and existing validation evidence. The [machine-readable census](source-inventory.json) records 120 production TS/TSX files under `src`/`app`, 76 frontend test files, 266 direct shared-client call expressions, and 34 route declarations. Declarations include a duplicated root and two wildcard routing boundaries; they are not 34 pages. File and expression counts are inventory aids, not coverage percentages.

Regenerate source tables from the repository root after installing the locked frontend dependencies:

```sh
node docs/redesign/audit/generate-inventory.cjs
```

The generator reads tracked source through the installed TypeScript AST. It does not execute application code. API paths supplied through variables are retained as expressions; resolve them with the contract map. CSS, static assets, OAuth SDK traffic and browser-extension entry points require the accompanying manual inspection. Runtime behavior is marked as prior evidence or unverified where this pass did not execute it.

## Architecture and technology

The application is a client-rendered React SPA packaged by Next, not a server-rendered Next route application. [Next configuration](../../../job-tracker-ui/next.config.js) exports static production assets and rewrites development deep links to the root. `app/page.tsx` and `app/[[...slug]]/ClientShell.tsx` load `ClientApp` with SSR disabled; `App.tsx` owns React Router. Nginx supplies the production SPA fallback and `/api` proxy. Preserve direct URL entry, refresh, history navigation and static deployment together.

| Concern | Current implementation | Redesign implication |
|---|---|---|
| Framework | Next 16, React 19, TypeScript strict; exact installed versions in lockfile | Keep build/output model unless a measured requirement needs a change |
| Navigation | React Router 7, outer public routes plus authenticated shell's inner `Routes`, lazy feature imports | Consolidate navigation metadata deliberately; do not accidentally introduce a second active route authority |
| UI | MUI 7, MUI X Data Grid/Date Pickers, Emotion, MUI icons; TanStack **Table**, not Query | Shared tokens and component composition can implement the brief without a library migration |
| Styling | [theme.ts](../../../job-tracker-ui/src/theme.ts), global CSS, MUI overrides, extensive inline `sx`, page-local styling | Theme exists, but duplicated shell/page color and surface choices weaken consistency |
| Typography | Archivo, loaded by app layout; theme typography variants | Preserve fallbacks and loading behavior; font self-hosting is a separate deployment/privacy choice |
| Data transport | One Axios instance in [api.ts](../../../job-tracker-ui/src/api.ts), thin typed domain wrappers and direct page calls | Keep the B02 interceptors and blob download behavior when extracting components |
| State | Local React state/effects; auth, account plan, theme, i18n, toast, prompt and confirm contexts | No Redux, Zustand or React Query store to replace; introduce a cache only for a demonstrated need |
| Async UI | `useViewResource`, resource-specific effects, operation polling, custom refresh events, component-local workspace tab cache | Preserve request sequencing, loading/error/refresh distinction and identity invalidation |
| Forms | Controlled MUI fields; many page-local draft states | Retain dirty guards and validation while extracting forms; do not add persistent private drafts implicitly |
| Documents | Canonical Career Profile, persisted CV settings/overrides, server HTML/PDF renderer, iframe preview | The editor is a domain application, not merely a form to restyle |
| Charts | Dashboard custom SVG/chart presentation | Preserve data meaning and add accessible alternatives where needed; no automatic chart-library replacement |

Dependencies and scripts: [package.json](../../../job-tracker-ui/package.json). Rendering entry and route wiring: [App.tsx](../../../job-tracker-ui/src/App.tsx). No frontend Next API route/server-action backend was found in the audited entry graph; application APIs live in .NET.

## Shared component responsibilities

| Existing foundation | Responsibility to retain / improve |
|---|---|
| `layout/AppShell` navigation model, `QuickCommandDialog` | Collapse/drawer navigation, active-route matching, capture actions, notifications, command search, logout and identity display |
| `theme`, `themePrefs`, `themeBootstrap`, global CSS | Light/dark/system preference, initial paint, semantic colors, spacing and responsive surfaces |
| `ViewStateNotice`, `useViewResource`, toast/confirm/prompt | Loaded, empty, failure, retry and confirmation behavior; give them consistent focus and announcement contracts |
| `RichTextField`, `TagsInput`, date controls | Plain text/markdown storage and form naming; avoid introducing HTML editing semantics during visual work |
| `ApplicationWorkspace`, `ApplicationAssets`, `jobWorkspaceRoute` | Full-page and overlay entry, section/deep-link aliases, derived artifacts and unsaved navigation |
| `components/cv/*`, `CvTemplateGallery`, `CvTemplateThumbnail`, `cvBuilder` | Capability-aware design settings, content editing, sample rendering, ordering and public/export contracts |
| `AiSectionAssistant`, cover-letter AI, interview AI, `aiWorkspace` | Context selection, entitlement states, current/suggested review, explicit acceptance and provenance |
| Account security/settings cards | OAuth links, mail connections, 2FA, sessions, exports, deletion and billing capabilities |

The complete component table includes four production modules outside the current ClientApp import graph: `Attachment`, `JobFlowBar`, `Markdown`, `UserManagementCard`. These are cleanup candidates only after checking non-app consumers and preservation coverage. App entry modules are naturally outside that graph. **Nothing is approved for deletion in Phase 1.**

## Localisation

[I18nProvider](../../../job-tracker-ui/src/i18n/I18nProvider.tsx) uses a typed EN/Bokmål dictionary, string interpolation, English fallback and `uiLanguage` local preference. Default is English unless a stored Norwegian code is present; authenticated `/auth/me` hydration restores the server preference. Changes PUT `/auth/preferences/language`; the document language becomes `en` or `nb-NO`. UI language and CV/AI document language are distinct controls and must remain so.

Most screen text is translated. There are real consistency gaps, for example the mobile job-card accessible name is hardcoded English at [JobTable:661](../../../job-tracker-ui/src/components/JobTable.tsx#L661). API errors and user-generated content are not automatically translated. Reusing translated labels, date/status formatters and long-string layouts should precede per-page copy changes. Browser accessibility tests currently force English; they do not prove Bokmål fit, pronunciation, errors or document formatting. Existing data and language preferences do not require Connor to decide a new default during this audit.

## Responsive behavior and accessibility

The code already adapts several workflows. `AppShell` changes to a drawer below 768 px; desktop sidebar has expanded/collapsed states. `JobTable` uses mobile cards and a separate filter arrangement. Kanban permits narrow-screen horizontal scrolling, keyboard pick-up/drop and a live region. Settings switch from tabs to a labelled select on small screens. The CV editor uses edit/preview panes below 900 px rather than shrinking the desktop split. These are preservation requirements, not missing features.

Responsiveness remains locally defined through mixed media queries and MUI breakpoints. Drawer/dialog nesting, long job titles, tables, email threads and document preview require a common layout contract plus real mobile testing. No new screenshot study or screen-reader session was performed in this Phase 1 pass.

The prior [validated accessibility evidence](../../audits/2026-09-07/validation/README.md#accessibility-conclusions) is **F14**, not draft-recovery F09. It measured shared contrast failures and a preview scroll-region focus failure after a viewport transition. Those are not evidence that every custom control is inaccessible. Current builder rich-text call sites supply labels and Kanban has keyboard support. `RichTextField` still permits unnamed usages in its optional props, and some Customize select patterns need an explicit accessible-name check. These are targeted verification points, not newly reproduced violations.

The automated axe suite samples eight routes and largely waits for `body`/`main`. It can miss loaded content, expanded editors, dialogs and errors. Before migration approval, use populated states, EN/NB, both themes, desktop/mobile; manually test keyboard and NVDA/Narrator, focus restoration, reauthentication, 200%/400% zoom, 320 CSS-pixel reflow, text spacing, forced colors, reduced motion and touch alternatives. Fix shared contrast semantics and the actual preview focus boundary before duplicating new page layouts.

## Principal conclusions

1. Preserve the working domain model and security boundaries; new page organization must not redefine ownership, CV persistence, AI acceptance or export formats.
2. The full job workspace, canonical Career Profile, contextual AI review, CV history and adaptive mobile surfaces already exist. The redesign should improve coherence and discoverability.
3. Shared visual semantics and loaded-state accessibility coverage are weaker than the broad test count suggests. Fix foundations before whole-page migration.
4. Five local dashboard visibility switches are not the proposed configurable dashboard. Ordering, resizing and cross-device persistence are future scope requiring a bounded contract.
5. The known standalone TypeScript failure reproduced during the audit; subsequent authorized release repair `a861ca4` corrected its test-only assertion after patched Next made it build-blocking. Standalone tsc now passes; an explicit standalone CI gate remains outstanding. Release/production and unresolved integrity gates must not be called green by implication.

Next work is **Phase 2 — Functional baseline**, subject to the gates in [RISKS_AND_MIGRATION](RISKS_AND_MIGRATION.md). No Phase 2 code, B07, or redesign component changes were made here.