95 lines
7.2 KiB
Markdown
95 lines
7.2 KiB
Markdown
# Aether (AE) SvelteKit Application
|
|
|
|
This project is a Svelte and SvelteKit based application, part of the Aether (AE) system. It uses Tailwind CSS and Skeleton for styling and some elements. This is the frontend UI/UX. The backend API uses Python FastAPI.
|
|
|
|
Core Aether modules
|
|
|
|
- accounts - client account, not user account
|
|
- hosted_files
|
|
- people
|
|
- users
|
|
- sites and site_domains
|
|
|
|
Additional Aether modules
|
|
|
|
- events
|
|
- presentation management - import the program data (events, session, presentations, presenters, event files, locations/rooms, devices)
|
|
- launcher - Technically this is used with presentation management. It is part of the native app that uses Electron. One of the libraries is for functions that only work when the site is opened in an Electron app. For example the regular browser can not move files around on the local computer or run local commands.
|
|
- badge printing
|
|
- lead retrieval - attendee tracking; QR codes
|
|
- journals - journal, documentation, notes, diary, blog, etc
|
|
- idaa - One of my clients
|
|
|
|
## Documentation
|
|
|
|
- TODO.md
|
|
- Svelte - Introducing runes - https://svelte.dev/blog/runes
|
|
- Svelte - Breaking changes in runes mode - https://svelte.dev/docs/svelte/v5-migration-guide#Breaking-changes-in-runes-mode
|
|
- Dexie.js - Getting Started - https://dexie.org/docs/Tutorial/Getting-started
|
|
- Dexie.js - API Quick Reference - https://dexie.org/docs/API-Reference#quick-reference
|
|
|
|
## Ignored Directories
|
|
|
|
The following directories are ignored for various operations (e.g., search, file listing) to focus on relevant source code:
|
|
|
|
- `build`
|
|
- `node_modules`
|
|
- `tests`
|
|
|
|
## Development Guidelines
|
|
|
|
### Svelte v5 and SvelteKit
|
|
|
|
This project uses Svelte v5 with runes enabled. This introduces significant differences from Svelte v4. It is critical to adhere to v5 conventions to avoid bugs.
|
|
|
|
- **Reactivity:** State is managed with `$state` and `$derived`. Props can be made two-way bindable with `$bindable`. Avoid direct mutation of props.
|
|
- **Event Handling (Updated 2025-11-20):**
|
|
- **DOM Events:** Use the lowercase `onevent` attribute (e.g., `onclick`, `oninput`). Event modifiers like `|preventDefault` may not work as expected; handle prevention logic inside the function (e.g., `event.preventDefault()`).
|
|
- **Component Events:** Continue to use the `on:eventname` directive for events dispatched from child components.
|
|
- **Stores and `liveQuery`:**
|
|
- To access the value of a store in Svelte v5, you must use the `$store_name` syntax (e.g., `$ae_api`).
|
|
- Dexie `liveQuery` returns an observable. To use it in a component, you must subscribe to it within `onMount` to avoid SSR errors. The value from the subscription should then be assigned to a `$state` variable.
|
|
- **Migration Guide:** For a comprehensive overview of the changes, refer to the official [Svelte 5 Migration Guide](https://svelte.dev/docs/svelte/v5-migration-guide).
|
|
|
|
### ID Convention: `id` vs. `id_random`
|
|
|
|
- **Always use `id_random`:** The API returns both a numeric `id` and a string-based `[obj_type]_id_random`. For all frontend operations (routing, data fetching, local storage), you **must** use the `_id_random` string.
|
|
- **Local Storage:** When saving an object to the local IndexedDB (Dexie), the `id_random` value should be aliased to both `id` (as the primary key) and `[obj_type]_id`. This ensures consistency with Dexie's expectations and the rest of the application's data access patterns.
|
|
|
|
---
|
|
|
|
## Refactoring Notes
|
|
|
|
### UI Library Compatibility Re-evaluation (2025-12-08)
|
|
|
|
**Context:** The project has been rolled back to a "mostly working" commit (`90ee6bb1`) after numerous failed attempts to update and integrate UI libraries (`@skeletonlabs/skeleton` and `flowbite-svelte`) with the current Svelte 5 and Tailwind CSS v4 environment.
|
|
|
|
**Key Issues Identified:**
|
|
1. **SkeletonLabs (`@skeletonlabs/skeleton`):** Attempts to upgrade to Skeleton v4.7.4 (which declares compatibility with Svelte 5 and Tailwind 4) consistently failed with a blocking build error: `[@tailwindcss/vite:generate:build] Cannot use @variant with unknown variant: md`. This error originates from Skeleton's pre-compiled CSS and indicates a fundamental incompatibility with the project's Tailwind/Vite build process.
|
|
2. **Flowbite-Svelte (`flowbite-svelte`):** Previous versions had peer dependency conflicts with Svelte 5. The currently installed version (`1.28.1`) allows `npm install` to complete, but its runtime compatibility in a Svelte 5 environment with Tailwind 4 is untested.
|
|
3. **Missing Components:** Previous attempts to abandon these libraries led to `ReferenceError`s (e.g., for `<Modal>`), confirming their use throughout the codebase.
|
|
|
|
**New Strategic Direction (Approved by User):**
|
|
1. **Hold off on upgrading `flowbite-svelte`:** Keep the current `1.28.1` version for now, as it doesn't block installation. Its functionality will be tested after SkeletonLabs is removed.
|
|
2. **Abandon `skeletonlabs/skeleton`:** Due to the persistent, unresolvable build error, we have decided to abandon SkeletonLabs and migrate away from it entirely.
|
|
3. **Systematically Replace UI Components:** Prioritize creating custom, drop-in replacements for essential UI components previously provided by SkeletonLabs (and potentially Flowbite-Svelte in the future). This will be done using pure Tailwind CSS and native Svelte components.
|
|
* The highest priority is the `<Modal>` component.
|
|
|
|
**Current State:**
|
|
* The `ae_app_3x_llm` branch has been reset to commit `90ee6bb1` to provide a stable, buildable base.
|
|
* The `feature/re_evaluate_ui_libs` branch contains the research and failed attempts to integrate Skeleton v4, and is saved for reference.
|
|
* The immediate next step is to verify that the `ae_app_3x_llm` branch builds and runs correctly before proceeding with the SkeletonLabs removal and component replacement plan.
|
|
|
|
### Data Fetching & Processing Pattern (2025-11-20)
|
|
|
|
A standard pattern for fetching, processing, and caching data has been established to ensure consistency and separation of concerns.
|
|
|
|
1. **API Function (`load_*`, `search_*`, etc.):** This function is responsible for interacting with the API. It takes parameters needed for the API call (e.g., `event_id`, search strings).
|
|
2. **Data Processor (`process_ae_obj__*_props`):** The API function's results are immediately passed to this dedicated processor function for the specific object type.
|
|
- The API function MUST pass any necessary contextual data (like a parent `event_id`) to the processor.
|
|
- The processor is responsible for all data shaping and enrichment before the data is cached.
|
|
3. **Handling API Inconsistencies:** The processor is the designated location for handling any inconsistencies in the data returned by the API.
|
|
- **Example (`event_badge`):** The `search__event_badge` API endpoint does not include the `event_id` in its results. The `process_ae_obj__event_badge_props` function now accepts the `event_id` as a parameter and injects it into each badge object before it's saved. This centralizes the fix and keeps the API-calling function clean.
|
|
4. **Database Caching (`db_save_ae_obj_li__ae_obj`):** After processing, the clean and consistent data is passed to the generic `db_save` function to be cached in IndexedDB.
|
|
|
|
This pattern isolates API logic from data shaping logic, making the code more modular, predictable, and easier to debug. |