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