Files

Scott Idem bd4bd360f7 docs: Update project documentation and session notes

- Updates `GEMINI.md` with a detailed summary of the days debugging session for the v3 Badges page.
- Updates `TODO.md` to mark recent bug fixes as complete and adds new tasks for outstanding issues (e.g., `order_by_li` fix).
- Updates `ARCHITECTURE.md` to reflect the current state of the tech stack (Tailwind v4, component library status).
- Creates `README.md` files for the new v3 Badges module and the legacy Lead Retrieval module to clarify their purpose and status.

2025-11-19 19:05:06 -05:00

5.5 KiB

Raw Blame History

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 (primary text and code editor, planned for rich text editing)
- Edra (TipTap based Rich Text Editor)
- Note: ShadEditor TipTap is present but marked for removal, with CodeMirror being the preferred solution for all text editing needs.
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.

5.5 KiB Raw Blame History