OSIT-AE-App-Svelte/TODO.md

One Sky IT's Aether UI/UX Project TODO

This is a list of tasks to be completed before the next event/show/conference.

---

Recent Accomplishments

• UI Libraries Updated: Successfully updated @skeletonlabs/skeleton to v4.7.4 and flowbite-svelte to v4.0.1. The issues preventing these updates, including build errors and runtime conflicts, were primarily resolved through careful integration and specific fixes, particularly those related to ae_comp__badge_template_form.svelte.

• Badges v3: Resolved a series of cascading build and runtime errors on the new badge search page. This involved restoring Skeleton CSS, fixing Svelte 5 event handler syntax (onsubmit|preventDefault), resolving a prop binding error (props_invalid_value), and temporarily disabling a problematic order_by_li API parameter to fix a network fetch error.

• Refactoring: Standardized data processing in events, archives, posts, and sponsorships modules using a new generic pattern.

• Bug Fix: Corrected data fetching logic for session-related presentations and files that were not displaying correctly due to id vs id_random issues.

• Core: Defined Account, Site, and Site_Domain interfaces in new files under src/lib/ae_core/.

• Journals: Improve the empty state message in src/routes/journals/+page.svelte.

• Journals: Add a loading indicator to the main journals page.

• IDAA: Add a loading indicator to the archives page (src/routes/idaa/(idaa)/archives/+page.svelte).

• Events: Add pagination to the main event list in src/routes/events/+page.svelte.

---

Big Picture Goals

• Everything needs to work with Svelte 5.x and SvelteKit 2.x.
• Able to cache data and mostly work offline.
• The new Events Launcher must be able to work offline and query the API for changes to data.
• The new Events Launcher must be able to run inside an Electron app and have access to local files and OS shell commands and applications. This includes loading a special library that only works in Electron.

---

Codebase Standardization

1. Naming Conventions

• Goal: Enforce a single, consistent naming standard across the entire codebase.
• Files:
  • Logic: ae_<module>__<concept>.ts
  • DB Definitions: db_<module>.ts
  • Svelte Stores: ae_<module>_stores.ts
  • Consolidate helper files (e.g., ae_core_functions.ts) into the above files.
• Functions & Variables:
  • Enforce snake_case for all function and variable names.
  • Deprecate and remove camelCase.
  • Deprecate and refactor ambiguous handle_ prefixes.
• Object & Property Naming:
  • Use singular nouns for objects and properties (e.g., example.id, not examples.id).
• List Suffixes:
  • Use _li for simple, unordered arrays.
  • Use _kv for key-value objects/maps.
• Process:
  • Refactor one module at a time to ensure internal consistency before moving to the next. Start with ae_core.
  • Update 2025-11-13: ae_core_functions.ts has been temporarily restored to resolve a critical issue. The refactoring of process_ae_obj__*_props() functions will now proceed module by module, ensuring stability at each step.

2. Component Standardization

• CodeMirror Migration: Replaced all instances of the old Tiptap editor with a new CodeMirror wrapper. This includes fixing initialization errors, enabling text wrapping, and ensuring content is correctly saved.
• Component Review: Audit third-party components to understand their conventions and isolate them from internal standards.

3. Aether Object Field Definitions

• Goal: Create a common way to define which fields can be sent in when creating or updating a record for all Aether objects.
• Process:
  • For each Aether object type, create a ae_<module>__<object>.editable_fields.ts file that exports a whitelist of editable fields.
  • Modify the create and update functions for each object type to use this whitelist to filter the data before sending it to the API.
  • Start with the event object type as a proof of concept. (DONE)
  • Apply this pattern to all other Aether object types.

---

Priority Tasks (Easy & Quick)

• API: Properly investigate and fix the order_by_li parameter in the search__event_badge function. The parameter is currently commented out as a temporary workaround to prevent a network fetch error.
• Formatting: Run npm run format to fix code style issues across the project.

---

Critical Functions for Review

These functions are frequently used and critical to the application's data flow. Reviewing and cleaning them up will significantly improve the codebase.

1. get_ae_obj_li_for_obj_id_crud_v2() (from src/lib/ae_api/api_get__crud_obj_li_v2.ts)

   • Why: This is the main function for fetching lists of data from the backend, used extensively across all modules.
   • Cleanup: Review parameters and return types for consistency, improve error handling, and add more detailed logging for debugging.

2. db_save_ae_obj_li__ae_obj() (from src/lib/ae_core/core__idb_dexie.ts)

   • Why: This function is the single point of entry for saving data to the local Dexie database, critical for performance and reliability.
   • Cleanup: Optimize for bulk operations, add robust error handling and logging, and ensure correct handling of updates to existing objects.

3. The process_ae_obj__*_props() family of functions (e.g., process_ae_obj__journal_props() from src/lib/ae_journals/ae_journals__journal.ts)

   • Why: These functions transform API data for the frontend and are a common source of bugs and inconsistencies.
   • Cleanup: Standardize their structure across all modules, ensure they are pure functions, and add unit tests for correctness.
   • Update 2025-11-13 (Temporary Rollback): The previous refactoring of these functions has been temporarily rolled back due to an InternalError. ae_core_functions.ts has been restored. The new plan is to refactor these functions module by module, ensuring stability at each step. The generic CRUD functions in core__crud_generic.ts were simplified to remove data processing and caching, delegating those responsibilities to the module-specific functions. The deprecated process_ae_obj__props function in that file was left in place but is no longer used by the generic CRUD functions.
   • Update 2025-11-20 (Successful Refactor): The event_badge module has been successfully refactored to use the new "API Function -> Processor -> DB Save" pattern. The process_ae_obj__event_badge_props function now handles inconsistencies in the API search results (i.e., a missing event_id) by accepting the event_id as a parameter and injecting it. This serves as a successful proof-of-concept for this architectural pattern.

4. Usage of liveQuery from Dexie

   • Why: liveQuery is powerful for reactive UIs, but current usage suggests complexity and potential issues.
   • Cleanup: Review liveQuery usage throughout the application, simplify queries, and investigate reactivity issues. Consider wrapping liveQuery in a custom Svelte store for a more predictable interface.

---

• Improve the e_app_codemirror_v5.svelte component and plan the migration from Tiptap to CodeMirror for rich text editing. The migration is complete, and the component has been improved to handle individual extensions and fix various bugs.

---

Core Module Improvements

1. Core Module Dashboard

• Create a central dashboard at /core to provide an overview and links to all core data management pages.

2. Account Management

• Route: Create a new route at /core/accounts.
• Data: Define the Account interface in a new file src/lib/ae_core/core__account.ts.
• API: Implement functions in core__account.ts for CRUD operations on accounts.
• UI:
  • Create a +page.svelte to list all accounts.
  • Create a [account_id] dynamic route to view and edit account details.

3. Site & Domain Management

• Route: Create a new route at /core/sites.
• Data: Define Site and Site_Domain interfaces in a new file src/lib/ae_core/core__site.ts.
• API: Implement functions in core__site.ts for CRUD operations on sites and domains.
• UI:
  • Create a +page.svelte to list all sites.
  • Create a [site_id] dynamic route to view and edit site details and manage associated domains.

4. Person Management

• Enhance: Improve the existing person management components under /core/person.
• UI:
  • Create a dedicated page for creating new person records.
  • Add search and filtering capabilities to the person list.

5. User Management

• Route: Create a new route at /core/users.
• UI:
  • Create a +page.svelte to list all users.
  • Create a [user_id] dynamic route to view and edit user details, including permissions.
  • Implement a component to link users to person records.

6. Hosted File Management

• Route: Create a new route at /core/hosted_files.
• UI:
  • Create a +page.svelte to list all hosted files with filters (e.g., by file type, uploader).
  • Implement a file viewer for common file types.
  • Add functionality to upload new files and associate them with other objects (e.g., a person, a journal entry).

7. Shared Lookup Lists

• Route: Create a new route at /core/lookups.
• UI:
  • Create a simple UI to view and manage the shared lookup lists (e.g., countries, time_zones).

---

Journals Module Improvements

Code Cleanup & Refactoring

• Consolidate Data Functions: Refactor ae_journals__journal.ts and ae_journals__journal_entry.ts to reduce code duplication, especially in data loading and processing functions.
• Remove Dead Code: Clean up commented-out code blocks and unused variables across the module.
• Logging: Implement a more structured logging solution to replace the widespread use of console.log.
• Promise Handling: Standardize promise handling to use async/await consistently and remove mixed .then() and async/await syntax.
• Type Safety: Replace any types with more specific interfaces, particularly in function parameters and API responses.

Features & Enhancements

• Offline Support: Improve offline capabilities by pre-fetching and caching more data. Review the current Dexie implementation for optimizations.
• Search & Filtering: Enhance the UI with more advanced search and filtering options for journals and entries (e.g., by date range, content, tags).
• User Experience (UX):
  • Implement better loading indicators and skeleton loaders.
  • Provide clearer empty state messages (e.g., "No journals found, create one!").
  • Improve error handling and provide more informative error messages to the user.
• Encryption: Review and enhance the encryption implementation for journal entries to ensure it is secure and user-friendly.
• Templates: Fully implement and document the "templates" feature for creating new journals and entries.

Bug Fixes & Potential Issues

• Reactivity: Investigate potential reactivity issues between Svelte stores and Dexie's liveQuery.
• Data Sync: Add logic to handle data synchronization conflicts between the local database and the server.
• Performance: Profile the application with a large number of journals and entries to identify and address any performance bottlenecks.

---

IDAA Modules Improvements

General

• Component Refactoring: Audit the ae_idaa_comp__ components and refactor them to be more generic and reusable where possible.
• State Management: Simplify state management by reducing the number of stores and triggers, and relying more on derived state and component props.

Archives Module (/idaa/archives)

• UI/UX:
  • Add a loading indicator while archives are being fetched.
  • Implement a more engaging "empty state" when no archives are available.
• Performance:
  • Implement pagination or infinite scrolling for the archive list.

Bulletin Board Module (/idaa/bb)

• UI/UX:
  • Improve the UI for creating and editing posts and comments.
  • Add a rich text editor for a better writing experience.
• Features:
  • Implement user-specific features, such as editing their own posts and comments.

Recovery Meetings Module (/idaa/recovery_meetings)

• Refactoring:
  • Simplify the search and filtering logic. The current implementation with setInterval is complex and could be replaced with a more modern approach using debouncing or reactive statements.
• UI/UX:
  • Make the search and filtering interface more intuitive and responsive.
  • Provide instant feedback to the user as they type in the search box.
• Performance:
  • Optimize the search query to be faster and more efficient.

---

Aether Events Module Improvements

General

• Dashboard: Create a central dashboard for each event at /events/[event_id] that provides an overview of the event and links to all the management pages.
• Component Refactoring: The module has a large number of ae_comp__ components. Audit and refactor them to be more modular and reusable.
• UI/UX Consistency: Ensure a consistent look and feel across all the different event management pages.

Core Event Management

• Event List (/events):
  • Add search and filtering capabilities to the main event list.
  • Implement pagination for the event list.
• Event Creation/Editing:
  • Create a dedicated page or modal for creating and editing events.

Sub-modules (/events/[event_id]/...)

• Sessions, Presentations, Presenters, etc.:
  • For each sub-module (sessions, presentations, etc.), implement a consistent set of features:
    • List view with search and filtering.
    • Detail view.
    • Create and edit forms.
    • Delete functionality with confirmation.
• File Management:
  • Improve the file upload component (ae_comp__event_files_upload.svelte) with features like drag-and-drop and progress bars.
  • Enhance the file list view with more details and actions.
• **Launcher (/events/[event_id]/launcher):
  • Add documentation to explain the purpose and usage of the launcher.
  • Improve the UI to make it more intuitive for users.
• **Badges (/events/[event_id]/badges):
  • Enhance the badge printing interface with more customization options.
  • Add a preview of the badge before printing.

Performance

• Live Queries: Review the use of liveQuery throughout the module and optimize for performance, especially on pages with a large amount of data.
• Data Loading: Implement more efficient data loading strategies to avoid fetching unnecessary data.

---

UI/UX Consistency

• Broad UI/UX Review: Conduct a comprehensive review of UI elements across the application to ensure consistency. This includes, but is not limited to:
  • Buttons (style, placement, wording)
  • Lists (style, actions)
  • Links vs. Buttons (correct semantic usage)
  • Menus (style, options)
  • Debug components and other developer-facing UI.
  • Wording: Standardize the text used in common UI elements (e.g., "Save", "Cancel", "Delete", "Add New").
  • Scope: This should be done on a per-module basis to ensure local consistency, with a goal of achieving global consistency where possible.
  • Note on IDAA: The idaa modules are semi-custom for a client and may have their own specific UI/UX requirements. Their consistency should be evaluated separately, keeping the client's needs in mind.
• Component Migration: Replace remaining Skeleton UI classes (e.g., preset-tonal-*, variant-filled-*) with standard Tailwind CSS to avoid CSS conflicts and dependency issues.

---

Scott's Quick Notes

These are just quick notes, thoughts, ideas, and reminders for myself.

• I need to explain the purpose and thought behind the data_store element or component and how it works. The short version: It is a hierarchy of database results, but only the last result is returned. The results are filtered by data store key/code, then by account_id, and then by for_type and for_id. This allows for shared data among accounts, but also account specific overrides. Finally, it allows for object specific overrides.
• Use old Events Leads module as reference for new one
• Use old Events Badges module as reference for new one
• Use old Events Launcher module as reference for new one
• The Launcher will need some work to make it work offline and in Electron
• Events Leads: mobile first, but still works on desktop
• Need to be able to enable and disable modules per event (e.g., some events may not need Leads or Badges)
• In theory session codes should be unique per event. This depends somewhat on the client's data and needs.
• The codes for locations/rooms should also be unique per event.
• The codes for devices should also be unique per event.
• Reports are manually created and shared among events and clients. We need to be able to enable/disable reports per event. Each report will have its own Svelte page.

Events modules and main landing pages

• Presentation Management
  • Manage
  • Session Search
  • View Session
  • View Presenter
  • Locations List
  • View Location
  • Devices List
  • View Device
  • Reports
• Launcher (desktop first; tablet second; mobile last)
  • Manage - Various admin and configuration options
  • Menu Section - Event; Location; Sessions; Show/Hide
  • Content Section - Shows session specific files; Shows session specific presentations; presentation specific presenters are shown per presentation; presenter specific files are shown per presenter
  • Header Section - Event Name; Location Name; Current Time; Offline/Online Status; Sync Status
  • Footer Section - Other status indicators; sync button
• Badge Printing
  • Manage
  • Print Badges
  • View Badge (show full preview before printing)
  • Review Badge (attendee confirms key info before printing; agree/disagree to terms; agree/disagree to lead retrieval and tracking)
  • Manually add Badge
  • Reports
• Lead Retrieval
  • Manage
  • View Leads
  • Add Lead (Scan or Manual Entry)
  • License Management and Payment (Stripe)
• Admin or Manage or Configure Event

New Directory Structure?

• src/lib/ - Shared libraries and components
• src/routes/core/ - Core Aether management module
  • sub-directories for:
    • accounts
      • account (by ID)
    • sites
      • site (by ID)
        • site_domains
          • site_domain (by ID)
    • people
      • person (by ID)
    • users
      • user (by ID)
    • hosted_files
      • hosted_file (by ID or partial hash match???)
    • lookups
      • (countries)
      • (state_provinces)
      • (time_zones)
• src/routes/events/ - Events main landing page and event management
• src/routes/events/[event_id]/(presentations)/ - Event presentation management module
  • sub-directories for:
    • sessions
      • session (by ID or code)
    • presentations
    • presenters
      • presenter (by ID or code???)
    • event_files
    • locations
      • location (by ID or code)
    • devices
      • device (by ID or code)
    • reports
      • report (by name of report)
• src/routes/events/[event_id]/(launcher)/ - Event launcher module
• src/routes/events/[event_id]/(badges)/ - Event badge printing module
• src/routes/events/[event_id]/(leads)/ - Event lead retrieval module
  • src/routes/events/[event_id]/+page.svelte - Event main dashboard
  • [event_id]/exhibit/[exhibit_id]/ - Exhibitor specific lead retrieval pages
• src/routes/journals/ - Journals module
• src/routes/idaa/ - IDAA custom modules
  • (archives)/ - Archives module
  • (bb)/ - Bulletin Board module
  • (recovery_meetings)/ - Recovery Meetings module
• src/lib/ae_core/ - Core Aether logic and data models
• src/lib/ae_events/ - Events module logic and data models
• src/lib/ae_journals/ - Journals module logic and data models
• src/lib/ae_idaa/ - IDAA custom modules logic and data models
• src/lib/components/ - Shared Svelte components
• src/lib/stores/ - Shared Svelte stores
• src/assets/ - Assets like CSS, Tailwind config, etc.???
• static/ - Static assets like images, fonts, etc.