Shared Maintenance & Users Pages

Status: active.

Folder-per-page structure

Shared domains use a folder-per-page layout under domains/shared/pages/*:

• users/list/index.tsx, users/list/skeleton.tsx
• users/create/index.tsx, users/create/skeleton.tsx
• users/detail/index.tsx, users/detail/skeleton.tsx
• maintenance/list/index.tsx, maintenance/list/skeleton.tsx
• maintenance/create/index.tsx, maintenance/create/skeleton.tsx
• maintenance/detail/index.tsx, maintenance/detail/skeleton.tsx

Each page:

• Owns its local skeleton file (no cross-page skeleton reuse).
• Wires TanStack Query hooks from .../queries/* and mutations from .../mutations/*.
• Is permission-aware: loading and action sections can be hidden when the current user lacks permissions.

Maintenance lifecycle & attachments (frontend contract)

• Pages call backend maintenance APIs only through lib/services/maintenance and domain-local query/mutation hooks.
• Attachment upload UI is centralized in maintenance/create/attachemnt.tsx and reused by:
  • maintenance/create/index.tsx (creator’s uploads)
  • maintenance/detail/index.tsx (creator/technician lifecycle uploads)
• The frontend never decides BEFORE/AFTER:
  • All uploads send only the file.
  • Backend infers type based on lifecycle (see maintenance lifecycle doc).
• Attachment UX:
  • Small grid preview inside the page.
  • Click to open full-screen overlay (image/video/pdf inline; other files via browser default/open).
  • Existing attachments are rendered with a toggle (All/Before/After) but use the backend’s type field only for display.

Users module as golden pattern

• Users shared pages (domains/shared/pages/users/*) are the reference for:
  • Folder-per-page layout and query/mutation wiring.
  • Permission-aware UI (hide actions when permission is missing).
  • Cache sync behavior via backend (cache/user/sync.ts).
• Maintenance shared pages now follow the same pattern:
  • Query/mutation hooks live under .../maintenance/queries/* and .../maintenance/mutations/*.
  • Pages are thin: they compose hooks + UI; no direct service calls.

What to follow for new domains

When creating a new shared domain (e.g. analytics, logs):

1. Use domains/shared/pages/<domain>/<page>/index.tsx + skeleton.tsx.
2. Keep fetch/mutation logic in queries/* and mutations/* files under the same domain.
3. Make skeletons page-specific and permission-aware:
   • Sections that depend on a permission should have matching skeleton sections that can be hidden.
4. Treat TanStack Query as server-state only; use context exclusively for app-wide state (auth, theme, system).