OSIT-AE-App-Svelte/documentation/AE__Data_Structures.md

Aether Project Data Structures

This document outlines the key data structures and their properties used within the Aether SvelteKit frontend project. It covers object properties, field definitions, and how data is managed.

1. Object Properties and Fields

1.1. Core Standard Fields

These fields are expected to be present in most Aether objects, providing a consistent base structure.

• id: Primary key for an object (internal use, often returned by the API as a randomized string value in place of the actual DB autonum).
• id_random: Randomly generated ID for an object (often used for external exposure or URL parameters).
• <object_type>_id_random: Specific random ID for an object (e.g., person_id_random).
• code: Short, unique identifier.
• name: Display name.
• enable: Boolean for active/inactive status.
• hide: Boolean for visibility.
• priority: Boolean/tinyint(1) ordering flag used by the object model.
• sort: Numeric value for ordering within a priority group.
• group: Categorization string.
• notes: General notes/comments.
• created_on: Timestamp of creation.
• updated_on: Timestamp of last update.

1.2. Journal Entry Fields

Journal entries use the shared object fields plus a few content-specific fields that matter in the UI and config modal.

• summary: Short entry summary shown in metadata and list contexts.
• content: Main body text for the entry.
• alert: Boolean flag used to highlight an entry as an alert.
• alert_msg: Supporting alert text shown when the alert flag is enabled.
• private / public / personal / professional: Visibility and audience flags used by the Entry Config modal.

1.3. Special Use Fields

Fields with specific purposes or conditional usage across different object types.

• for_type: Indicates the type of object this object is linked to (e.g., 'account', 'event').
• for_id: The ID of the object this object is linked to.
• archive_on: Timestamp indicating when an object was archived.
• passcode: A password or access code associated with an object.
• external_id: An identifier from an external system.

1.4. Configuration and JSON Fields

Fields designed to store structured data in JSON format.

• cfg_json: Configuration data for an object, stored as a JSON string.
• data_json: General purpose data for an object, stored as a JSON string.
• linked_li_json: A list of linked items, stored as a JSON string.

1.5. Special Generated Fields (Client-side)

These fields are generated on the client-side, primarily for facilitating UI logic, such as sorting. They are not typically stored in the backend database.

• tmp_sort_1: Temporary sort field 1.
• tmp_sort_2: Temporary sort field 2.
• tmp_sort_3: Temporary sort field 3.

1.6. Future Standard Fields

A list of potential future standard fields, often prefixed with obj_. These are conceptual and represent planned expansions to the data model.

• obj_id, obj_ext_uid, obj_ext_id, obj_import_id, obj_code, obj_account_id, obj_passcode, obj_type, obj_type_ver_id, obj_name, obj_summary, obj_outline, obj_description, obj_enable, obj_enable_on, obj_archive_on, obj_hide, obj_priority, obj_sort, obj_group, obj_cfg_json, obj_notes, obj_created_on, obj_updated_on.

2. Data Sorting

Standardized sorting orders are applied across various data lists to ensure consistent presentation.

• Default/General Sorting: group > priority (flag) > sort > updated_on/created_on
• Specific Sorting (e.g., for time-based events): type > start_date/time > code or name

3. Data Storage Mechanisms

3.1. Local Storage

Used for client-side persistence of various application states and configurations.

• api: Stores API-related settings and tokens.
• app: Stores global application settings and preferences.
• core: Stores settings and data specific to core modules.
• <module>: Stores settings and data specific to extended modules (e.g., journals, events).
• <custom>: Stores settings and data specific to custom modules (e.g., idaa).

3.2. IndexedDB (Dexie.js)

Used for more structured client-side data storage, often for caching, offline capabilities, and larger datasets.

• ae_core_db: The primary Dexie database instance for core application data.
• <module>: Module-specific database instances (e.g., db_journals for journal data).
• <custom>: Custom module-specific database instances (none currently defined, but reserved for future use).

3.3. IndexedDB LiveQuery Usage

Dexie's liveQuery is used to provide reactive data streams from IndexedDB.

• lq__xyz_obj: Represents a read-only liveQuery result for a single object.
• lqw__xyz_obj: Represents a writable liveQuery result, typically used for forms and data binding.
  • Note: When using lqw__xyz_obj, developers must carefully manage updates to avoid conflicts with the underlying liveQuery and ensure data integrity.