Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Create ARCHITECTURE.md, COMPONENTS.md, and DATA_STRUCTURES.md for comprehensive project documentation.

Browse Source
This commit is contained in:
Scott Idem
2025-11-13 15:33:39 -05:00
parent cfed92e8a5
commit 882b9b5bc7
3 changed files with 317 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
ARCHITECTURE.md Normal file
View File

@@ -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.
* `<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. 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.

132
COMPONENTS.md Normal file
View File

@@ -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`

72
DATA_STRUCTURES.md Normal file
View File

@@ -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).
* `<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.
### 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.
* `<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.