jobtrackingapp/docs/redesign/phase-3/COMPONENT_ARCHITECTURE.md

# Component architecture

ARC-15; affected contracts are in each row and the full [impact matrix](PRESERVATION_IMPACT_MATRIX.md). Names describe responsibilities, not a mandate for one file per name. Retain existing implementations until a scoped consumer needs the shared behavior.

## Retain, refactor, consolidate or add

| Target responsibility | Existing owner | Disposition and boundary | PRES |
|---|---|---|---|
| AppShell / Sidebar | layout/AppShell; App nav/title helpers | **Refactor** existing grouped/collapsed/drawer presentation; preserve auth tree, collapse and active matching. Extract Sidebar only if it simplifies this owner | E07–E09 |
| PageHeader | AppShell title/breadcrumb/rightActions plus local page headers | **Consolidate** heading/action hierarchy; keep one h1 and no duplicated global/detail header | E07, E08, W01, C06 |
| WorkspaceHeader | local WorkspaceHeader in ApplicationWorkspacePage; CV header | **Retain/refactor** per-domain content; share layout only, not save/status semantics | W02, C06, C10 |
| MetricCard | DashboardView metricCards/Card | **Refactor** as data-labelled presentation; no fetching/AI in a card | S01 |
| DashboardWidget | DashboardView SectionCard + visibility menu | **Add later** catalogue/order/size wrapper in Phase 8; existing visibility migrated | S02 |
| DataTable / MobileDataCard | JobTable and CompaniesTable use MUI Table; admin uses MUI X grid | **Retain** engines; share toolbar/state/cell styles where proven. TanStack Table is installed but no current src import was found; do not introduce it as a migration prerequisite | J05, J06, J08, A01 |
| StatusBadge | pipeline statusLabel/statusTone and inline Chips | **Consolidate** presentation using existing status semantics; custom values retained | J07, W02, S01 |
| FilterBar | JobTable inline/mobile controls; SavedViewsMenu | **Refactor** presentation around same filters/saved-view owner | J05, S03 |
| EmptyState / ErrorState / LoadingSkeleton | ViewStateNotice, useViewResource, local skeletons | **Consolidate** semantics/retry/focus; existing owner still decides data/error states. Do not create three wrappers when one composition suffices | E08 and all loaded pages |
| QuickPreviewDrawer | ApplicationWorkspace optional props; no active host | **Add only after parity fixture**, read-only summary/navigation. Do not mount second full editor | W01, J05 |
| CommandPalette | QuickCommandDialog + App keyboard trigger | **Refactor/extend** existing action callbacks and owner-scoped result reads | E07, J04, J08 |
| NotificationCentre | NotificationsPopover + Notifications API | **Refactor/extend** same store; new full route only when needed | S02, W11, W12 |
| AIAction | AiSectionAssistant, CoverLetterAiAssistant, InterviewAiAssistant, document AI tab, aiWorkspace | **Consolidate** state/entry presentation, retaining each API/context and entitlements | C11, W03, W06, W09, S04 |
| AIReviewDiff | current/proposed builder, extraction and letter views | **Consolidate** readable comparison/reject/apply UI; domain validations and payload identity remain local | C03, C11, W06 |
| DocumentCard / row | CvBuilderPage, Attachments, SubmittedPackagesSection | **Add index projection view**, reuse domain open/download handlers; never merge resource persistence | C05, W07, W08 |
| WorkspaceTabs | ApplicationWorkspace tabs; CV studio tabs; settings TabPanel | **Refactor** semantics/responsive selector where repeated; preserve dirty guards and active resource | W01, C06, S03 |
| SettingsSection | SettingsView SectionCard; security/provider cards in ProfilePage | **Consolidate** layout/help/errors only; server/local settings scopes stay separate | E04–E06, M06, S03–S05 |
| Form fields and dates | MUI TextField/Select/Autocomplete/DatePicker; RichTextField, TagsInput | **Retain + targeted accessibility refactor** for names/help/errors. No form framework or HTML storage migration | C01, C07, W06, J03 |
| Dialog / Drawer / confirmation | MUI, confirm, prompt, toast | **Retain** mechanics; standardize focus/name/dirty behavior and mode styling | E08, W01, S05 |
| Task row / Timeline | ApplicationChecklist, ApplicationTimeline, InterviewPrep | **Retain/refactor** domain structures; no universal task/event object | W02, W04, W09, W10 |
| Chart container | DashboardView SVG helpers | **Add small composition only as needed** for title/period/values table; keep calculations in owner/service | S01 |
| Theme providers/tokens | theme, ThemeProvider, themePrefs, themeBootstrap, I18nProvider | **Retain/refine**; no second theme, locale or preference authority | E08 |
| Auth/session/API boundary | App, api, sessionBoundary, accountPlan | **Retain unchanged** unless a separately evidenced defect; server identity/permissions remain authoritative | E02–E09, S04 |

Unreachable Attachment, JobFlowBar, Markdown and UserManagementCard in the earlier census are not authorized deletions. Shared component extraction must prove all existing consumers, not assume file size or duplicate names require a new abstraction.

## Data and state ownership

Presentation primitives accept current state/callbacks, not raw account IDs with their own API clients. Form draft, persistence revision, selected source and send attempt remain in the relevant domain owner. A UI “scope” label is not authorization. No generic hook that conflates account profile singleton, identified CV, package capture and mail send.

Keep API cancellation/provenance and private-tree lifetime. Existing resource loads may be split only with latest-response and owner boundary tests. Avoid duplicating network loads between a header, sidebar panel and content. Newly consolidated Documents/Analytics need explicit bounded reads, not hidden browser crawls.

Reusable components should emerge from actual repeated behavior. E.g. MUI already implements Button/Dialog semantics; standardizing its theme is enough. AI review can share a comparison frame while retaining different extraction/block/letter acceptance validators. Do not flatten them into one unsafe Apply callback.

## File and implementation discipline

Keep current folder layout initially. Add small shared modules next to existing components/theme only when first consumers migrate. No bulk rename, barrel re-export tree, new package/workspace or Storybook dependency in Phase 4. Use existing test/browser fixtures for representative states.

Do not move App's provider order, router creation and navigation presentation in the same change. Do not change CV save owner while extracting visual fields. Do not run mail draft/send restructuring alongside generic document work. Components listed “add later” are not Phase 4 scope just because their names appear in this document.