# Entity Forms & Audit System # Entity Forms & Audit System
Relevant source files The following files were used as context for generating this wiki page: - [src/lib/components/FormPageLayout.svelte](src/lib/components/FormPageLayout.svelte) - [src/lib/components/entity-list-table/utils/auditable-fields.ts](src/lib/components/entity-list-table/utils/auditable-fields.ts) - [src/lib/components/entity-list-table/utils/cell-formatting.ts](src/lib/components/entity-list-table/utils/cell-formatting.ts) - [src/lib/components/ui/metadata-loading/MetadataLoading.svelte](src/lib/components/ui/metadata-loading/MetadataLoading.svelte) - [src/lib/composables/useAuditBox.ts](src/lib/composables/useAuditBox.ts) - [src/lib/composables/useEntityMetadata.svelte.ts](src/lib/composables/useEntityMetadata.svelte.ts) - [src/lib/entity-list/sheets/panels/ColumnsPanel.svelte](src/lib/entity-list/sheets/panels/ColumnsPanel.svelte) - [src/lib/entity-list/sheets/panels/SearchInPanel.svelte](src/lib/entity-list/sheets/panels/SearchInPanel.svelte) - [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte](src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte) - [src/lib/shell/sheets/SheetHeader.svelte](src/lib/shell/sheets/SheetHeader.svelte) - [src/lib/shell/sheets/SheetHost.svelte](src/lib/shell/sheets/SheetHost.svelte) - [src/lib/shell/sheets/sheet-manager.svelte.ts](src/lib/shell/sheets/sheet-manager.svelte.ts)
The Entity Form and Audit system provides a standardized architecture for viewing and editing records while maintaining a comprehensive trail of changes. It centers around a unified layout component that integrates record metadata with a reactive audit display and a version history explorer. ### System Overview The system is built on three main pillars: 1. **Standardized Layout**: The `FormPageLayout.svelte` component provides a consistent UI for create/edit views, including header actions and the footer-based Audit Box. 2. **Audit Metadata**: Managed via `useAuditBox` and `useEntityMetadata`, this layer handles the extraction and formatting of system fields like `created_at`, `updated_by`, and `version`. 3. **Change Tracking**: The `VersionHistoryPanel` provides a deep-dive timeline into every modification made to a record, utilizing a delta-parsing engine to show field-level changes. ### High-Level Component Relationship The following diagram illustrates how the form components interact with the audit composables and the global sheet system. **Form & Audit Architecture** ```mermaid graph TD subgraph "UI Layer" FPL["FormPageLayout.svelte"] VHP["VersionHistoryPanel.svelte"] ML["MetadataLoading.svelte"] end subgraph "Composables & Logic" UAB["useAuditBox.ts"] UEM["useEntityMetadata.svelte.ts"] AFV["auditable-fields.ts"] end subgraph "Global Systems" SM["sheet-manager.svelte.ts"] API["api.ts (apiFetch)"] end FPL --> UAB FPL --> UEM UAB --> AFV UAB -- "openSheet()" --> SM SM -- "renders" --> VHP VHP -- "apiFetch()" --> API UEM -- "apiFetch()" --> API ``` **Sources:** [src/lib/components/FormPageLayout.svelte:5-7](), [src/lib/composables/useAuditBox.ts:3-5](), [src/lib/shell/sheets/sheet-manager.svelte.ts:74-84](), [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:2-5]() --- ### Form Page Layout & Audit Box The `FormPageLayout.svelte` component is the standard wrapper for all entity detail views. It manages the vertical distribution of the form content and houses the **Audit Box** in its footer. * **Audit Box Logic**: Driven by the `useAuditBox` composable, it automatically categorizes metadata columns into `created`, `updated`, `deleted`, and `sync` groupings [src/lib/composables/useAuditBox.ts:19-33](). * **Version Badge**: If a `version` field exists in the data, a clickable badge is rendered. Clicking this badge triggers `openVersionHistory`, which opens the audit timeline in a side sheet [src/lib/components/FormPageLayout.svelte:76-88](). * **Field Formatting**: The system uses `getAuditableDisplayValue` to handle "by" fields (e.g., `created_by`). If a corresponding `_name` field exists (e.g., `created_by_name`), it is prioritized for display [src/lib/entity-list/table/utils/auditable-fields.ts:43-65](). For implementation details on props and metadata validation, see **[Form Page Layout & Audit Box](#5.1)**. **Sources:** [src/lib/components/FormPageLayout.svelte:38-44](), [src/lib/composables/useAuditBox.ts:83-85](), [src/lib/entity-list/table/utils/auditable-fields.ts:29-31]() --- ### Version History Panel The `VersionHistoryPanel.svelte` is a specialized side-sheet component that fetches and renders the audit log for a specific record. * **Data Retrieval**: It communicates with the backend via `/api/v1/entities/{entity}/{uuid}/audit` with support for pagination [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:60-69](). * **Visual Timeline**: Uses a `Timeline` component to display changes chronologically. Each entry is color-coded based on the action: * `CREATE`: Emerald * `UPDATE`: Sky * `RESTORE`: Amber * `DELETE`: Red * **Delta Parsing**: The `formatAuditDelta` function iterates through the changes in an audit entry, translating technical field keys into localized labels and formatting values (badges, dates, or booleans) for human readability [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:165-200](). For details on the delta parsing pipeline and semantic coloring, see **[Version History Panel](#5.2)**. **Sources:** [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:102-116](), [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:159-163](), [src/lib/shell/sheets/sheet-manager.svelte.ts:34-38]() --- ### Entity Metadata Integration The system relies on `useEntityMetadata` to understand which fields are considered "auditable" for a given entity. | Feature | Code Entity | Description | | :--- | :--- | :--- | | **Metadata Fetching** | `useEntityMetadata` | Loads the `EntityMetadata` structure from the backend [src/lib/composables/useEntityMetadata.svelte.ts:34-41](). | | **Validation** | `auditingColumns` check | Ensures the metadata contains the necessary audit column definitions to prevent UI breakage [src/lib/composables/useEntityMetadata.svelte.ts:44-60](). | | **Loading State** | `MetadataLoading.svelte` | A specialized spinner component shown while entity metadata is being retrieved [src/lib/components/ui/metadata-loading/MetadataLoading.svelte:22-32](). | **Data Flow: Metadata to Audit UI** ```mermaid sequenceDiagram participant Page as Entity Edit Page participant UEM as useEntityMetadata participant API as Backend API participant FPL as FormPageLayout participant UAB as useAuditBox Page->>UEM: loadMetadata() UEM->>API: GET /api/v1/entities/{name}/meta API-->>UEM: Return EntityMetadata UEM-->>Page: meta object Page->>FPL: Render with meta.list.auditingColumns FPL->>UAB: getUpdatedFields(auditingColumns) UAB-->>FPL: formatted strings (e.g. "Updated by Admin") ``` **Sources:** [src/lib/composables/useEntityMetadata.svelte.ts:5-12](), [src/lib/components/FormPageLayout.svelte:18-20](), [src/lib/composables/useAuditBox.ts:16-33]() ---