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

Aether Project Architecture

This document outlines the overall architecture and key technologies used in the Aether SvelteKit frontend project.

1. Project Overview

The Aether project is a Svelte and SvelteKit based application, utilizing Tailwind CSS and Skeleton for styling and UI elements. It serves as the frontend UI/UX for the Aether system, which interacts with a Python FastAPI backend.

2. Core Technologies

• Frontend Framework: Svelte 5 and SvelteKit v2
  • Routing: SvelteKit's file-system based routing.
• Styling: Tailwind CSS v4
• UI Component Libraries:
  • Skeleton (Design System, Tailwind Components, Functional Components - being phased out due to conflicts with Tailwind CSS v4)
  • Flowbite (Tailwind Components)
  • Custom Components (a growing library of ae_comp__* and element_* components)
• Text/Code Editors:
  • CodeMirror 6.x (element_editor_codemirror.svelte) — source/code editing, markdown
  • TipTap (element_editor_tiptap.svelte) — WYSIWYG rich-text for content fields (IDAA, Journals, Leads notes)
• Icons: Lucide Icons (SVG Icons)
• Markdown Parsing: marked library
• State Management: Svelte stores, potentially with liveQuery from Dexie for reactive IndexedDB interactions.

3. Module Structure

The Aether project is organized into several modules, categorized as Core, Extended, and Custom.

3.1. Official Modules

Core Modules

These are foundational modules essential for the application's basic functionality.

• Accounts: Minimal implementation.
• Files: Manages hosted files.
• People: Minimal implementation for person records.
• Sites: Minimal implementation for site configurations.
• Users: Minimal implementation for user management.

Extended Modules

These modules provide additional features and functionalities.

• Archives: Minimal implementation.
• Events: Includes features for Badges and Presentation Management.
• Posts: Minimal implementation.
• Journals: Manages journal entries.

Custom Modules

These modules are tailored for specific client needs.

• IDAA: Includes Archives, Bulletin Board (BB), and Recovery Meetings functionalities.

4. Data Storage Mechanisms

4.1. Local Storage

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

• api: API-related settings.
• app: Global application settings.
• core: Settings and data specific to core modules.
• <module>: Settings and data specific to extended modules.
• <custom>: Settings and data specific to custom modules.

4.2. IndexedDB (Dexie.js)

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

• ae_core_db: Core database instance.
• <module>: Module-specific database instances.
• <custom>: Custom module-specific database instances (none currently defined).

5. Data Sorting

Standardized sorting orders are applied across various data lists.

• Default/General: group > priority > sort > updated_on/created_on
• Specific (e.g., Events): type > start_date/time > code or name

6. Object Properties and Fields

A set of standardized field names and types are used across Aether objects.

6.1. Core Standard Fields

These fields are expected to be present in most Aether objects.

• id: Primary key for an object (internal use, often a UUID).
• 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: Numeric value for ordering.
• sort: Numeric value for ordering.
• group: Categorization string.
• notes: General notes/comments.
• created_on: Timestamp of creation.
• updated_on: Timestamp of last update.

6.2. Special Use Fields

Fields with specific purposes or conditional usage.

• for_type: Indicates the type of object this object is linked to.
• for_id: The ID of the object this object is linked to.
• archive_on: Timestamp for archiving.
• passcode: Password or access code.
• external_id: ID from an external system.

6.3. Configuration and JSON Fields

Fields designed to store JSON data.

• cfg_json: Configuration data in JSON format.
• data_json: General data in JSON format.
• linked_li_json: List of linked items in JSON format.

6.4. Special Generated Fields (Client-side)

Fields generated on the client-side, primarily for sorting or UI logic.

• tmp_sort_1
• tmp_sort_2
• tmp_sort_3

6.5. Future Standard Fields

A list of potential future standard fields, often prefixed with obj_. These are currently conceptual and not yet fully integrated.

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

7. Runtime Environment: Browser vs Electron

The Aether SvelteKit frontend runs in a standard web browser in almost all cases. The Electron native app is a very specialized exception with a narrow, specific purpose.

7.1. Standard Browser (Default)

All Aether modules run in a regular browser (Chrome, Chromium, Firefox, Safari). This includes:

• Badge printing — window.print() works well across Chrome, Chromium, and Firefox. Chrome is recommended for onsite badge printing stations.
• All CRUD operations, event management, journals, IDAA, reports, etc.
• No special browser configuration required.

7.2. Electron Native App (Specialized — Pres Mgmt Launcher Only)

The Electron app (aether_app_native_electron/) exists solely to support the Events Presentation Management Launcher. It provides OS-level capabilities that a browser sandbox cannot:

• Control of third-party presentation software (PowerPoint, Keynote, LibreOffice Impress)
• Local filesystem access for slide file management
• Hardware telemetry for connected devices

What Electron is NOT used for:

• Badge printing (browser works well)
• Any other Aether module
• Any general-purpose Aether functionality

The bridge is exposed as window.aetherNative (set by Electron's preload script). All code that calls window.aetherNative should degrade gracefully when it is undefined (i.e., in a normal browser). See: src/lib/electron/electron_relay.ts.

When to assume Electron is available: Only inside the /events/[event_id]/(launcher)/ route group, and only when the page was loaded from the native app.

8. IndexedDB LiveQuery Usage

• lq__xyz_obj: Used for general read-only access to liveQuery results.
• lqw__xyz_obj: Used for forms and binding values, representing a writable snapshot of liveQuery results.
  • Note: Care must be taken when binding to lqw__xyz_obj to manage updates and potential conflicts with the underlying liveQuery.