Frontend

Entity Forms & Audit System

Relevant source files

The following files were used as context for generating this wiki page:

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:

Standardized Layout: The FormPageLayout.svelte component provides a consistent UI for create/edit views, including header actions and the footer-based Audit Box.
Audit Metadata: Managed via useAuditBox and useEntityMetadata, this layer handles the extraction and formatting of system fields like created_at, updated_by, and version.
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

Code
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.

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.

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

Code
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

Last modified on July 13, 2026

Development Conventions & AI Agent Rules Entity List Table