cesnimda
6.6 KiB
Component architecture
ARC-15; affected contracts are in each row and the full impact matrix. 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.