diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000..42edd362 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,113 @@ +# 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 3.x (with plans to upgrade to 4.x when ShadCN is ready) +* **UI Component Libraries:** + * ShadCN (Tailwind Components) + * Skeleton (Design System, Tailwind Components, Functional Components - with plans to upgrade to v3) + * Flowbite (Tailwind Components) +* **Text/Code Editors:** + * CodeMirror 6.x (for text and code editing) + * Edra (TipTap based Rich Text Editor) + * **Note:** ShadEditor TipTap is present but marked for removal, with CodeMirror being the preferred solution. +* **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. +* ``: Settings and data specific to extended modules. +* ``: 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-specific database instances. +* ``: 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). +* `_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. 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. diff --git a/COMPONENTS.md b/COMPONENTS.md new file mode 100644 index 00000000..88c852b0 --- /dev/null +++ b/COMPONENTS.md @@ -0,0 +1,132 @@ +# Aether Project Components + +This document details the various UI components used throughout the Aether SvelteKit frontend project, categorized by their scope and functionality. + +## 1. Aether Components (UI/UX) + +### 1.1. System Components +These components are part of the core application shell and provide global functionalities. +* **`header`**: Application-wide header. +* **`main/module`s**: Main content area for modules. +* **`footer`**: Application-wide footer. +* **`app`**: Provides global application functionalities such as: + * Refresh application state. + * Clear IndexedDB. + * Clear local storage (settings). + * Toggle iframe visibility (also updates URL parameter). + * Copy current URL. + * Generate and display QR codes. +* **`menu`**: Various menus for different purposes: + * **`mode`**: Edit mode toggle, more options (all or details). + * **`access_type`**: Passcode input, clear access. + * **`user`**: Sign in/out, reset password, email link, change username and email. + * **`theme`**: Mode (light/dark), name (theme list). +* **`debug`**: Developer-facing tools: + * Toggle debug mode (also updates URL parameter). + * Show core and module storages. + * Manually set initial timestamp. +* **`scroll_to`**: Navigation controls for scrolling: + * Scroll to top of the page. + * Scroll page up. + * Scroll page down. + * Scroll to bottom of the page. + +### 1.2. Core Components +These are reusable components that provide common functionalities across different modules. +* **`copy_btn`**: A button to copy content to the clipboard. + * Properties: `clipboard`, `bind:value`, `btn_text`, `btn_html`. +* **`txt_editor`**: A basic text area editor. +* **`md_editor`**: Markdown editor. + * Uses CodeMirror. + * **Note:** ShadEditor TipTap is present but marked for removal. +* **`html_editor`**: HTML editor. +* **`media_player`**: Component for playing media files. + * Properties: `hosted_file`, `archive_content`, `media_player`. + * Bindings: `bind:host_id`, `bind:media_type`. + * Status: `stopped`, `paused`, `playing`. +* **`hosted_file_li`**: Manages a list of hosted files, making them available for selection. +* **`hosted_file_link_to`**: Lists links per object, with bindings to add/remove links. +* **`upload_to_host`**: Component for uploading files to the host. + * Handles multiple files. + * Properties: `link_type`, `link_id`, `inner fragment` (label html). + * Bindings: `bind:trigger`, `bind:show_spinner`, `bind:show_percent`. + * Status: `started`, `uploading`, `finished`. +* **`upload_file_tbl`**: Table for uploaded files, includes checks for duplicate file hashes and removal from the list. +* **`download_from_host`**: Component for downloading files from the host. + * Bindings: `bind:host_file_id`, `bind:filename`, `bind:file_ext`. + * Properties: `btn inner fragment`. + * Bindings: `bind:trigger`, `bind:show_spinner`, `bind:show_percent`. + * Status: `started`, `downloading`, `finished`. +* **`data_store`**: Component for interacting with data stores. +* **`ae_crud`**: Generic CRUD (Create, Read, Update, Delete) component. + * **Note:** Needs simplification. + * Properties: `obj`, `prop`, `current_value`. + * Bindings: `bind:value`, `bind:trigger`, `inner fragment`. +* **`ae_obj_prop_val`**: A wrapper for a function to manage object property values. + * Bindings: `bind:obj_type`, `bind:obj_id`, `bind:obj_prop`, `bind:obj_value`, `bind:obj_new_value`, `bind:trigger`, `bind:show_spinner`, `bind:show_percent`. + * Status: `status`, `result`. +* **`sql_qry`**: Component for executing SQL queries. +* **`obj_tbl`**: Object SQL results table or similar. +* **`qr_scanner`**: Component for scanning QR codes. +* **`websocket`**: Component for WebSocket communication. + +### 1.3. Main / Module Components +These are components specific to main application sections or individual modules. +* **`menu`**: + * **`options`**: Various settings, show/hide content and options, limit, sorting options. + * **`actions`**: Various actions, sign in/out, email. + +### 1.4. Object Menu +A standardized menu for interacting with objects. +* **Properties Displayed:** `id`, `name`, `group`, `priority`, `sort`, `alert`, `hide`, `enable`, `note`. +* **Future Properties:** `ext_id`, `ext_sys_id`, `code` (not yet ready). +* **Actions:** `create`, `view`, `edit`, `update`, `hide`, `disable`, `delete`, `alert` (message), `archive` (not yet ready). +* **Future Actions:** `copy`, `import`. +* **Sort Options:** + * `[default]`: `group > priority > sort (ASC/DESC) > alert > name` + * `[sort_updated]`: `group > priority > sort (ASC/DESC) > alert > updated_on > created_on` + * `[priority_updated]`: `group > priority > updated_on (ASC/DESC) > created_on` + * `[priority_name]`: `group > priority > name (ASC/DESC) > sort > alert > updated_on > created_on` + * `[name]`: `priority > name (ASC/DESC) > sort > alert > updated_on > created_on` + * `[created_on]`: `priority > created_on (ASC/DESC)` + * `[updated_on]`: `priority > updated_on (ASC/DESC) > created_on` + +## 2. Pop-ups +Standardized structure for various types of pop-up elements. +* **`modal_header`**: + * `title` + * `close` button +* **`modal_main`**: Main content area of the modal. +* **`modal_meta`**: Meta-information section. +* **`modal_footer`**: + * `close` button +* **`Pop-up Modal (blocking)`**: A modal that blocks interaction with the rest of the page. + * `modal position` +* **`Pop-up Modal Inline`**: A modal that appears inline with content. + * `inline`, `inline-block`, `block` display options. +* **`Pop-up Dialog`**: A dialog box. + * `dialog position` + +## 3. Containers +Generic container types used for layout and grouping. +### 3.1. Navigation +* `link` +* `download` + +### 3.2. Forms +* `save` button/action +* `clear value` action +* `set null value` action + +### 3.3. Other Containers +* `help`: Blue themed container. +* `info`: Blue themed container. +* `alert`: Yellow themed container. +* `warning`: Orange themed container. +* `error`: Red themed container. +* `message`: Green themed container. + +## 4. CSS Styling for UI Elements +* **Warning/Hide Buttons:** `variant-soft-warning hover:variant-filled-warning` +* **Error/Delete/Disable Buttons:** `variant-soft-error hover:variant-filled-error` +* **Submenu:** `flex flex-row items-center justify-center gap-1` diff --git a/DATA_STRUCTURES.md b/DATA_STRUCTURES.md new file mode 100644 index 00000000..82e4db57 --- /dev/null +++ b/DATA_STRUCTURES.md @@ -0,0 +1,72 @@ +# 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 a UUID). +* `id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters). +* `_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. + +### 1.2. 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.3. 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.4. 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.5. 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 > 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. +* ``: Stores settings and data specific to extended modules (e.g., `journals`, `events`). +* ``: 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-specific database instances (e.g., `db_journals` for journal data). +* ``: 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.