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.

Deliverables and method

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

Read the ten documents required by ASTRA_HANDOFF, 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 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:

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 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, 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, 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. Rendering entry and route wiring: 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 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. 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 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 reproduces. The source baseline is documented, but 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. No Phase 2 code, B07, or redesign component changes were made here.