docs(redesign): complete Phase 1 audit checkpoint

This commit is contained in:
cesnimda
2026-09-10 07:22:09 +02:00
parent fc749b1a30
commit 2d0f131a99
5 changed files with 131 additions and 4 deletions
@@ -2,6 +2,8 @@
This is the current source-backed preservation baseline. **All rows are Preserve** until a later approved migration explicitly records relocation, merger or deprecation. Target-only ideas are separated at the end. A component's existence proves implemented behavior, not live provider availability or usability quality. The [API census](API_CALL_SITES.md) and [component census](COMPONENT_INVENTORY.md) supply the individual call sites/consumers behind these groups.
There are **57 protected capability groups**. The [completion summary](PHASE1_SUMMARY.md) classifies existing behavior, UX improvements, new requirements and known defects separately. A preserve-and-improve classification never removes a capability from this contract; known defective behavior is not the intended behavior to preserve.
## Entry, navigation and account
| ID | Current user-facing function | Source / important contract |
@@ -57,8 +59,8 @@ This is the current source-backed preservation baseline. **All rows are Preserve
| C03 | CV/file upload and extraction, rebuild/improve/reprocess, progress/history, diff, explicit low-confidence selection, accept/discard, retry/cancel | `CareerProfilePage`, `/profile-cv/*`; uploaded proposal is not silently canonical truth |
| C04 | Evidence bank: sourced statement/title/category/tags, add/list/delete and truthfulness guidance | `CareerEvidenceBank`; evidence belongs to profile owner and is not AI-invented experience |
| C05 | CV library create/name/copy/delete, template gallery and real sample thumbnails, publish/unpublish/share and PDF download | `CvBuilderPage`, `cvBuilder`; separate public slug from numeric private ID |
| C06 | Studio Template/Content/Customize/AI Tools/History navigation; debounced preview and save state | `CvBuilderEditor`; existing mobile edit/preview and desktop split must retain parity |
| C07 | Built-in item visibility/order, custom sections, preset/free-text section catalog, item/content overrides, hide/remove, keyboard reorder | `CvBuilderEditor`, `components/cv/*`; selected profile source and overrides remain distinguishable |
| C06 | Studio Template/Content/Customize/AI Tools/History navigation; debounced preview, page boundaries/automatic fit and save state | `CvBuilderEditor`; existing mobile edit/preview and desktop split must retain parity; automatic fit is not a manual zoom control |
| C07 | Built-in item visibility/order, custom sections, preset/free-text section catalog, item/content overrides, hide/remove, native section drag and keyboard reorder | `CvBuilderEditor`, `components/cv/*`, `useDragReorder`; selected profile source and overrides remain distinguishable |
| C08 | Template-capability-aware typography/colors/header/headings, skills presentation/groups, one/two-column and sidebar settings, photo/icons | `CvCustomizeTab`, theme registry; retain unsupported-setting handling and server render equivalence |
| C09 | A4/Letter, density, margins/spacing, date format, document language, per-section rows/grid/compact/bubbles and columns | `cvBuilder`, `CvCustomizeTab`, content controls; do not drop advanced controls merely to simplify layout |
| C10 | Undo/redo of editor settings, save queue, unsaved guard, history/version restore and preview lifecycle | `CvBuilderEditor`; current queue serializes one mounted editor only, not concurrent browsers |
@@ -89,10 +91,12 @@ This is the current source-backed preservation baseline. **All rows are Preserve
| A02 | Admin audit event list/detail, supported undo and job restore | `AdminAuditPage`; preserve event/ownership semantics rather than generic mutation buttons |
| A03 | Separate system health/build/database/AI/email status, SMTP settings/test, AI probe, CV corpus benchmark and maintenance run controls | `AdminSystemPage`; sensitive config values/logs must not move into personal dashboard |
## Target brief items that are not current features
## Relationship to the target brief
The target grouped navigation would reorganize an existing collapsible sidebar. Jobs/Table and Kanban can become view choices over the existing APIs. Dedicated Analytics/Documents/Notifications destinations would relocate embedded capabilities. They are not permission to delete offers, reminders, correspondence review, operations or legacy URLs.
Dashboard drag/order/resize/reset and cross-device persistence are new work beyond the five local booleans. A general assistant/chat, goals system, new brand/name and additional email/calendar providers are not implied by existing contextual AI or integrations. Retain implemented Google/Outlook calendar actions even though the product brief describes broader calendar ambitions as future work.
Dashboard drag/order/resize/reset are new work beyond the five local booleans; cross-device persistence is an unresolved scope choice. Optional goals, a new logo and expanded contextual access are separately identified additions; a general chat platform, product rename or additional providers are not implied by existing AI/integrations. Retain implemented Google/Outlook calendar actions even though the product brief describes broader calendar ambitions as future work.
The [new-requirements matrix](PHASE1_SUMMARY.md#3-genuinely-new-requirements-and-conditional-additions) distinguishes required versus suggested/future additions: expanded command search/actions, application density, configurable status mappings, per-task scheduling, intent-led onboarding, contextual-assistant access and aggregate admin metrics. Existing raw custom status values, job reminders, onboarding checklist, operational admin dashboard and CV document density must remain intact; none alone establishes the corresponding new contract. The brief asks for contextual assistant access, not necessarily a general chat platform; a new logo is required, while a name change remains undecided.
During migration, extend this table with destination, regression test and review evidence per ID. Do not treat a screen screenshot or a count of passing tests as proof that all rows survived.
+117
View File
@@ -0,0 +1,117 @@
# Phase 1 completion summary
Completed **2026-09-10** on `codex/ui-redesign-audit`. This is an audit checkpoint, not a verified production release. **No visual redesign, component-library migration, route restructuring, Phase 2 implementation or B07 work has begun. B06/F04 closure remains open.**
The detailed [architecture assessment](README.md), [functionality ledger](FUNCTIONALITY_INVENTORY.md), [route/workflow map](ROUTE_MAP.md), [API/identity map](API_AND_IDENTITY.md), [component inventory](COMPONENT_INVENTORY.md), [test assessment](TEST_INVENTORY.md) and [migration risks](RISKS_AND_MIGRATION.md) form this completed audit. The source census remains valid: the only `src`/`app` change since its checkpoint is the separately documented interview test assertion. This final completion commit changes documentation only.
## 1. Existing functionality to preserve
All **57 preservation IDs** in the full ledger remain protected, including features that already satisfy the brief. These are capability groups, not a claim of 57 individual controls or complete runtime test coverage.
| Ledger IDs | Complete functional coverage by area |
|---|---|
| E01–E09 | Public plans; local and provider authentication; registration/verification/reset/email change; 2FA/recovery/trusted devices; sessions/logout; account identity/avatar/password; sidebar/command search; theme/localisation/shared feedback; cross-account state isolation |
| J01–J10 | NAV discovery and saved alerts; reviewed manual/URL/paste capture; extension/bookmarklet capture; table/mobile cards/filter/sort/pagination/columns/saved views; edit/bulk actions/trash/restore; Kanban; companies/contacts; offer comparison; JSON/CSV export and import/conversion |
| W01–W12 | Full job workspace and quick overlay/deep links; progression/timeline; analysis/match/strategy; checklist; CV selection/tailoring; cover letters/review/version restore; application drafts/frozen submitted packages; attachments; interview prep/debrief; reminders/calendar/notifications; asynchronous operations |
| C01–C12 | Canonical Career Profile and long-tail sections; overview/completeness/history; file extraction/diff/accept/discard; evidence bank; CV library/copy/publish/share; responsive editor/preview; item and section visibility/order/overrides; template-aware customization; page/document settings; undo/redo/save/history; section/document AI review; private/public PDF |
| M01–M06 | Job correspondence records; Gmail search/import/thread linking; global inbox/filter/attachment information; provider compose/reply/drafts/review/send/delivery uncertainty; Gmail review decisions; Google/Microsoft/IMAP connections |
| S01–S05 | Personal analytics/next actions; owner-local widget visibility/onboarding/notifications; follow-up/email/table/theme/language preferences; AI privacy/usage/Free–Pro/billing capabilities; account export/encrypted backup/lifecycle/deletion |
| A01–A03 | Admin user/role/reset/deletion guards; audit/undo/restore; separate operational diagnostics/email settings/AI probes/CV benchmarks/maintenance |
The route map accounts for **31 concrete patterns: 29 page patterns and two compatibility aliases**. It also records not-found/error boundaries and non-route entry points: capture query strings, command search, notification links, workspace section/tab aliases, OAuth popups and public CV slugs. Embedded Documents, Analytics and Notifications functionality is inventoried even though these are not current standalone routes.
Protected workflows include discover/capture → review/create → analyse/match → select/tailor CV → prepare material → submit/freeze package → track/remind → interview/outcome; import CV → review canonical profile → create/edit/publish/export variant; inbox/import → link → draft/review/send; and account/session/admin lifecycle. Exact sub-actions and source owners are in the ledger; a redesigned page must not silently omit its nested functions.
## 2. Existing functionality needing UX improvement
These are **preserve-and-improve**, not missing features or authorization to implement them now. Assessment concerns coherence/discoverability unless a defect is explicitly identified in section 4. No new user study or visual/manual accessibility session is claimed.
| Existing capability / IDs | Already satisfies the brief | Remaining UX work |
|---|---|---|
| Navigation and command launcher, E07 | Collapsible sidebar, section support, mobile drawer, active child-route matching, Ctrl/Cmd+K job/company search | Main features currently share one broad Manage group. Improve grouping and discoverability; retain account/admin separation. Extra command capabilities are new scope below |
| Job views and workspace, J05–J07, W01–W12 | Desktop table/mobile cards, saved views, keyboard Kanban, full job page and shared quick overlay, next actions and artifact relationships | Present table/board as views of one workspace; clarify section hierarchy and full-page/preview transitions. Preserve every alias, status and nested workflow |
| Career and CV, C01–C12 | Canonical profile, document overrides, real template previews, page boundaries/automatic fit, drag and keyboard reorder, undo/history, desktop split/mobile edit-preview, PDF | Improve source-versus-override clarity, advanced-control discovery and preview focus. Keep advanced existing controls despite the brief's shorter suggested list |
| Contextual AI, W03/W05/W06/W09, C03/C11 | Context selection, source material, preview/diff and accept/reject already exist | Standardize current/suggested/evidence presentation and locked/error states. Presence of review UI is not proof that every AI output is factually correct |
| Dashboard/onboarding, S01–S02 | Metrics/trends, next actions, five owner-local visibility switches, guided checklist/dismissal | Improve hierarchy and empty/loaded states; additional widget/layout contracts are new work |
| Mail/documents/notifications, M01–M06, W06–W08/W11–W12 | Drafts, explicit send/review, delivery states, job-linked files, inbox/review, reminders and operations | Make destinations and status distinctions easier to find. Unified navigation relocates these capabilities; it does not replace their persistence contracts |
| Calendar and account/settings/admin, W11, E02–E06, S03–S05, A01–A03 | Follow-up/deadline Google/Outlook event creation and ICS; account controls; separate admin tools | Preserve provider availability/permission handling and clarify account versus career versus provider identity; keep operational diagnostics separate from personal data |
| Themes/localisation/responsiveness, E08 and all flows | MUI theme, light/dark/system, EN/Bokmål and existing workflow adaptations | Standardize tokens, layout/focus/error states and test populated EN/NB/mobile surfaces. New density and brand choices are separate requirements |
## 3. Genuinely new requirements and conditional additions
These distinctions come from comparing the brief to the current handlers/models, not from treating every desired noun as a missing page. Proposed defaults are not permission to change stored data.
| Brief requirement | Current boundary / incremental work | Scope decision |
|---|---|---|
| Dashboard ordering, resizing, reset and remembered layout | [DashboardView](../../../job-tracker-ui/src/components/DashboardView.tsx) persists only `cards/activity/funnel/companies/skills` visibility flags | New layout behavior. Decide device-local versus cross-device persistence before backend/schema work; Phase 8 |
| Expanded command palette | [QuickCommandDialog](../../../job-tracker-ui/src/components/QuickCommandDialog.tsx) searches jobs/companies and has six static commands | Add CV/document search, CV creation, Career Profile, appearance/language and contextual commands where specified; reuse existing actions |
| Comfortable/compact application density | Theme/table display preferences exist; CV **document** density exists | New application preference affecting chosen dense surfaces; do not confuse it with document density |
| Configurable statuses and category mapping | [JobPipeline](../../../JobTrackerApi/Services/JobPipeline.cs) preserves free-text/custom values; [pipeline.ts](../../../job-tracker-ui/src/pipeline.ts) defines fixed groups and an Other fallback | New configuration/mapping workflow. Preserve Waiting/Ghosted, raw values, analytics and rules; never replace statuses with the brief's suggested list |
| Per-task due dates and notifications | [Checklist model](../../../JobTrackerApi/Models/ApplicationChecklistItem.cs) stores status/order/completion; follow-up and deadline dates belong to the job | New task scheduling contract if adopted. Existing job reminders do not prove per-task scheduling |
| Optional editable weekly goals | Existing analytics and onboarding do not store a weekly target | New optional capability with supportive defaults; no universal application quota |
| Intent-led onboarding and suggested profile preferences | [OnboardingChecklist](../../../job-tracker-ui/src/components/OnboardingChecklist.tsx) links existing account/profile/job/provider steps; it does not collect the brief's initial job-seeker intent | New intake/personalization scope if adopted. Suggested desired-role/remote/salary preferences need an explicit data contract; do not infer them from job salary/location |
| Shared contextual-assistant entry and command actions | Domain-specific AI controls/wrappers exist; no persistent shell assistant is wired into the current route graph | New interaction surface/reuse work. A general-purpose chat platform is not required to satisfy contextual access |
| Aggregate product/admin dashboard and candidate metrics | [AdminSystemPage](../../../job-tracker-ui/src/views/AdminSystemPage.tsx) is operational; personal dashboard analytics already exist | Cohort/adoption/conversion and CV-performance additions require defined measures, permitted aggregate data and availability. Candidate widget lists are not a promise every metric exists or must ship; correlation is not causation |
| Manual CV preview zoom | [CvBuilderEditor](../../../job-tracker-ui/src/views/CvBuilderEditor.tsx) automatically fits page width; drag reorder, pagination and history already exist | Manual zoom is a recommended incremental control, not a reason to rebuild the preview or declare all builder capabilities missing |
| Logo and brand treatment | Existing mark/theme remain functional | New logo is required by the brief; exact accent/name decisions are deferred. No automatic product rename |
| Broader event/provider support, priority/favourite and optional quick-drawer form | Existing calendar actions cover follow-up/deadline; current quick overlay is functional; suggested fields/providers are not all current contracts | Conditional product additions or presentation choices. Broader calendar is explicitly future scope. Do not remove existing integration or introduce schema merely to match illustrative examples |
Grouped navigation, a Jobs view switch, and clearer Documents/Analytics/Notifications destinations belong to **section 2's reorganization of existing behavior**; they do not automatically require new APIs or a new resource model. New analytical measures or cross-job queries must be scoped separately from relocating existing views.
## 4. Known baseline defects and technical/UX debt
The existing validated queue owns these defects; this final audit pass records them and does not fix or re-audit them. Prior independently reproduced findings remain distinct from source-only risks and unresolved production evidence.
| Status / owner | Known issue relevant to redesign | Required treatment |
|---|---|---|
| Open, F01 / D01–D03 | CV/profile/job lost-update and atomic-history/projection contracts | Preserve existing history; a mounted editor's save queue does not solve concurrent writers. Coordinate before changing persistence/conflict UX |
| Open, D04–D07 | Duplicate creation intent, concurrent/omitted byte accounting and export/history growth | Preserve current warnings/quotas; do not silently add idempotency, retention or storage redesign |
| Open, F14 / A01–A03 | Previously validated shared contrast and preview keyboard-scroll defect; thin loaded-state accessibility coverage | Track structural fixes separately; no compliance claim from shell-only axe samples |
| Open, W01/W05 | Calendar date/timezone correctness and private unsaved-draft recovery scope | Preserve current semantics while documenting defects. Do not persist private drafts across accounts or invent new storage |
| Open, R01b/R02/R03/R05 and paid-lifecycle queue | Production DB fallback validation, consistent backup/restore/rollback proof, worker survival, billing entitlement/deletion | Separate owners and release gates. No schema work before recovery proof; billing UI cannot establish entitlement correctness |
| Historical error fixed; R01a partly open | `interview-prep.test.tsx:120` TS2571 reproduced, then corrected with a test-only matcher during authorized release repair | Standalone tsc now passes. Explicit standalone CI gate is still missing; do not continue calling TS2571 an active failure |
| Current CI block | Run 743 browser worker SIGSEGV, then timeout/closed-browser errors; deploy skipped | Obtain runner diagnostics before another release attempt. Do not weaken gates or label the crash an application assertion failure |
| Source-backed maintainability/UX debt | Two router layers; large stateful forms; mixed breakpoints; hardcoded shell colors alongside theme; hardcoded English mobile accessible name | Small, tested future changes. Module size is not performance evidence; cleanup candidates are not approved deletions |
| Unverified risk | Router identity changes with display preferences; optional labels/select patterns; loaded EN/NB/theme/mobile/manual accessibility gaps | Targeted regression/manual checks needed. Do not promote these to reproduced security defects |
| Open, B06/F04 | Actual deployed ingress trust and bypass protection remain unproven | Separate production verification below; repository checks cannot close it |
See [validated ticket boundaries](../../audits/2026-09-07/validation/implementation-queue.md), [test limitations](TEST_INVENTORY.md) and [regression-risk evidence](RISKS_AND_MIGRATION.md). Identity isolation, record concurrency and creation idempotency remain three different contracts.
## Functionality preservation contract
Every ledger ID defaults to **preserve**. Before migrating a workflow, record its destination, retained actions/state transitions, exact API/data meaning, permission/session boundary and regression evidence. Relocation/merger must retain capability; deprecation requires an explicit documented decision. No deletion is approved in this audit.
Preserve direct links/aliases/capture/OAuth flows; owner/session/role/entitlement checks; canonical Career Profile versus document overrides; AI preview/reject/apply and factual provenance; dirty/conflict recovery and private-state disposal; server drafts/history/frozen packages and uncertain-send behavior; publication versus private downloads; B01–B05 safety contracts; typed date/JSON/CSV/PDF formats and Norwegian text. Existing backend defects are recorded for their own tickets, not redefined as acceptable intended behavior.
A migrated workflow needs same-account success and cross-account denial, populated/empty/error/locked states, EN/NB, light/dark, desktop/mobile, keyboard/focus and artifact checks appropriate to its behavior. A screenshot, module presence or aggregate test count alone is insufficient preservation evidence.
## Frontend architecture and stack assessment
**Retain the current stack.** React 19/strict TypeScript is a client-rendered SPA packaged by Next 16 static export, with React Router 7 owning application routes and nginx handling static/deep-link/API routing. MUI 7, MUI X, Emotion and MUI icons already provide the foundation; styling combines central theme/global CSS and substantial local `sx`. TanStack Table is used, not TanStack Query. No Redux/Zustand/cache-platform replacement is warranted.
Local React state and focused contexts own forms/auth/theme/language/plan/feedback; shared Axios owns cookies/XSRF/B02 request provenance/cancellation and blob downloads. The API census contains **266 call expressions**; ownership is server-enforced. Improve shared component contracts and existing tokens before page migration. No demonstrated limitation justifies replacing the component library, routing or backend.
## Test and CI baseline
| Evidence | Result / limit |
|---|---|
| Latest completed CI, run 743 at main `27657f3` | **916/916 backend**, zero skips; **67 suites / 298 frontend tests**; lint, dependency audits, Compose/safety/parser and production builds passed |
| Same CI browser gate | **6 passed / 12 failed**; initial worker SIGSEGV, retry timeout and closed-browser errors. Deploy skipped; not a green release |
| Local release checks at `a861ca4`, unchanged source since | **18/18 browser**, standalone tsc, lint and static build passed; installed npm audit zero vulnerabilities. Local success does not replace CI |
| Prior B06 focused tests | **166 backend, 3 Compose, 6 native Production ingress, 9 native B04 HTTP** checks passed; no actual Traefik/nginx topology |
| Accessibility/test census | 76 frontend test files, 106 backend test-source files; general axe samples eight routes in English, not all loaded interactions/manual accessibility |
| Final audit-only validation | **621 local links valid, 57 unique ledger IDs, 31 route patterns, 266 API rows, all 120 production source files match the census**; only intervening `src` change is the documented test assertion. Secret scan and diff checks pass; application suites were not rerun for prose edits |
Exact commands, historical failures and classification are preserved in [TEST_INVENTORY](TEST_INVENTORY.md) and the [release report](../../audits/2026-09-07/validation/b06-completion.md#final-release-retry--2026-09-10). Previous CI/build changes were separate authorized release/baseline repairs: Compose availability, Linux fixture/runtime/TLS-test portability, blocking dependency advisories and the test-only TS2571 correction. They are not redesign implementation, and this final pass adds none.
## Unresolved production validation
**B06 implementation complete, but B06 runtime/production closure and F04 remain open.** Intended path: Traefik → host 3000 → nginx → internal API 8080. Docker Desktop's inference-socket failure prevented the real local container chain. No verified production SSH alias was available; no credentials or CI secrets were obtained.
Actual nginx startup/fail-closed configuration/restart, Traefik socket peer and trusted CIDR, backend client IP/scheme, real-chain B02/B04 behavior, host/container listeners, firewall/NAT/IPv6 and independent direct-port denial still need evidence. Public DNS/valid HTTPS were observed, but intended-address inventory and the HTTP redirect to unreachable HTTPS port 444 remain unresolved. Live `/health` last observed **2026-09-10 05:07 UTC**, version **299**, ready; this is not deployment of the pushed audit repairs. Exact safe operator commands and expected evidence remain in the [B06 report](../../audits/2026-09-07/validation/b06-completion.md).
## Recommended Phase 2 starting point
Start only when separately authorized: **a bounded functional-baseline session, with no layout or route changes**. Add the explicit standalone type-check script/CI step while coordinating with runner repair; map the 57 preservation IDs to existing assertions and add the highest-risk missing tests for route/overlay/capture parity, populated CV/profile overrides and AI accept/reject. Preserve real API/B02 identity tests and B01/B03/B04/B05 suites.
Exit requires a documented pass/fail/unavailable baseline, meaningful loaded-workflow proof and a preservation checklist tied to tests. Existing defects stay separately ticketed; failed tests are not made green by weakening expectations. Record-integrity and recovery prerequisites govern later persistence/schema work. Phase 3 navigation proposals and Phase 4 visuals follow their own checkpoints; no stable/live tag or F04 closure is warranted while their evidence is missing. Branding, product additions and cross-device layout decisions do not block this audit's completion.
+3
View File
@@ -4,6 +4,8 @@ Date: 2026-09-09. Source checkpoint: `97fce89c002fe86e737ca7387170321d464b80d7`
**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.
Finalized 2026-09-10: [Phase 1 completion summary](PHASE1_SUMMARY.md) explicitly separates existing functionality to preserve, existing functionality needing UX improvement, new/conditional requirements and baseline defects/debt. It includes the preservation contract, validation limits and bounded Phase 2 starting point. All 57 ledger IDs remain protected; this is a separate documentation checkpoint, not a stable/live release tag.
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.
@@ -12,6 +14,7 @@ Release status, 2026-09-10: main `27657f3` is pushed. Run 743 passed 916 backend
| Handoff requirement | Evidence |
|---|---|
| Final summary and four-way scope classification | [Phase 1 completion summary](PHASE1_SUMMARY.md) |
| 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 |