Files

Scott Idem cd06fb79e8 Saving the new documentation for the Launcher project plans. Finally moving this to a new version of Electron and pretty much starting from scratch.

2026-01-21 12:11:47 -05:00

7.4 KiB

Raw Blame History

Aether (AE) SvelteKit Application

This project is the frontend UI/UX for the Aether (AE) system, built with Svelte 5 (SvelteKit), Tailwind CSS, and Skeleton. It interfaces with a Python FastAPI backend.

🎯 Core Mandates (Safety & Efficiency)

Fast is slow. Slow is fast. Deliberate, careful progress is better than rushed, error-prone actions.
Fail fast. If a change breaks the system, revert immediately to the last known working version before attempting a new fix.
Commit early and often. Working changes MUST be committed before starting major new modifications. Always test before committing.
Verify. Perform syntax checks and basic compile verification before finalizing any code change.
Trust but verify. Always verify tool outputs, assumptions, and system state before proceeding.

🏗️ Architecture & Standards

Reactivity & Stores

Svelte 5 Runes: Use $state, $derived, and $effect for component-level reactivity.
Dexie LiveQuery: Results from liveQuery are observables. You MUST use the $ prefix (e.g., $lq__obj) in templates and logic to subscribe to the live data. Failure to do so will result in accessing the observable object instead of its data.
Persistence: Use svelte-persisted-store for data that must survive page refreshes (e.g., ae_loc, journals_loc).
Initialization: Always initialize reactive state ($state) outside of $props() destructuring. Use untrack inside $effect when synchronizing props to local state to prevent infinite loops.

ID Convention (Triple-ID Pattern)

Standard: Use id, [obj_type]_id, and [obj_type]_id_random consistently.
Primary Key: Always use _id_random (string) for routing, data fetching, and local storage.
Local Storage: Alias id_random to both id (PK) and [obj_type]_id when saving to Dexie.

API V3 Implementation

Robustness: Use the standardized primary helpers (get, post, patch, delete) in src/lib/ae_api/.
SSR Parity: Helpers support custom fetch injection for SvelteKit server-side execution.
Bootstrap Paradox: Use the unauthenticated bypass (x-no-account-id: "Nothing to See Here") for site/domain lookups.
Envelopes: Helpers automatically handle the {data: ...} envelope returned by the backend.

Data Pattern

Fetch: API Function calls the V3 endpoint.
Process: Dedicated process_ae_obj__*_props function handles data shaping, parent ID injection, and computed fields.
Cache: Save cleaned data to IndexedDB via db_save_ae_obj_li__ae_obj.

🛠️ Tooling & Orchestration

Aether Ops (MCP Extension)

verify_api_integrity: Headless verification of the FastAPI stack.
schema_sync: Syncs Pydantic models to TypeScript interfaces in src/lib/types/ae_types.ts.
ae_obj_info: Metadata lookup for Aether objects.
UE-AE-01 Vision: Moving towards a unified agent with total system awareness across MariaDB, FastAPI, SvelteKit, and Nginx.

📂 Modules Overview

Core Modules

Identity: accounts, people, users.
Infrastructure: sites, site_domains.
Storage: hosted_files.

Feature Modules

Events: Presentation management, Badge printing, QR tracking.
Journals: Documentation, notes, and AI-assisted summarization.
IDAA: Client-specific logistics and video conferencing (Jitsi).

📝 Development History (Consolidated)

Hardening & V3 Stabilization (2026-01-20)

IDAA Search Hardening: Isolated IDAA Recovery Meetings to a specialized qry_ae_obj_li__event_v2 function. Restored full 154-result capacity and implemented "Inclusive OR" location logic (Virtual/In-person).
System Lookups Restoration: Fixed a TypeError by correctly exporting get_ae_obj_li_for_lu in api.ts. Reverted lookup endpoints to stable V2 paths to resolve V3 "Configuration error" 500s. Added Country Subdivisions card to the lookups page.
V3 Search Refinement: Updated general qry_ae_obj_li__event to use the standardized q property for full-text search and robust "Body + Header" context injection.
Git State Resolution: Resolved a complex 12-commit rebase conflict involving manifest.webmanifest and ae_events__event.ts. Pushed a clean, branded, and stable state to the remote repository.
Crash Prevention: Hardened meeting detail views with null-checks for contact_li_json to handle legacy/incomplete data.

Hardening & V3 Stabilization (2026-01-19)

Structured Error Handling: Updated api_get, api_post, and api_patch helpers to extract rich metadata (meta.details) from V3 API 400/500 responses. Standard FastAPI detail fields are automatically wrapped for consistency.
JWT Race Condition Fix: Implemented "Early Injection" in +layout.ts. The JWT is now read directly from localStorage during bootstrap, ensuring the first requests of a page load are correctly authenticated.
Archives Stability: Resolved a critical async race condition in load_ae_obj_li__archive and hardened _process_generic_props to handle non-array API responses.
Fail-Fast Hardening: Added HTTP 400 and 422 to the Fail-Fast protocol to prevent unnecessary retries on invalid requests.
V3 Hardening Tests: Enhanced the /testing dashboard with "Live V3 Header Inspection" and automated audits for Permissive Mode and Structured Errors.
Status: Main AE Events module verified working with V3 Search; IDAA isolated to V2 for stability.

Hardening & Svelte 5 Modernization (2026-01-16)

Hardening: Improved resilience for Journals and IDAA modules against API downtime and "ghost" account fallback.
Commit: Atomic refactor of 15 files focusing for type safety, Svelte 5 runes, and API robustness.
Fixes: Resolved download progress crashes in api_get_object_v1 and corrected event handling in several Svelte 5 components.
Status: Investigating Badge Rendering issues where badge_template_obj fails to load despite badge_obj being available.

Config & Stability Sprint (2026-01-14)

Standardization: Refactored Module, Journal, and Entry modals into a unified "Config" pattern with consistent iconography (Wrench/Gear/Zap).
Auto-Save: Implemented background persistence for Status & Security fields using non-blocking API calls.
Payload Hardening: Established a strict whitelisting pattern for update payloads to eliminate HTTP 400 "Unknown column" errors.
UX Refinement: Replaced complex Journal menus with a streamlined "Config" button and dedicated "Quick Actions" tabs.

Journals Module Refactor (2026-01-08)

Modularization: Extracted JournalEntry_AITools and JournalEntry_Metadata from the 3000+ line main view.
UI/UX: Standardized on Lucide icons. Implemented 3-state header toggle (View/Eye/Save).
CodeMirror: Migrated to CM6 with updateListener pattern for Svelte 5 compatibility.

Jitsi God Mode (2025-12-15)

Architecture: Hybrid XMPP bot for server-side stats collection, pushing real-time meeting metadata to MariaDB.

Build & Library Health (2025-12-08)

Upgrades: Successfully updated to SkeletonLabs v4.7.4 and Flowbite-Svelte v4.0.1.
Staging: npm run build:staging verified and clean of import/export errors.

🔗 Resources

Reference Stubs: agents_sync/technical/references/ (Svelte 5, Dexie, FastAPI).
Official Docs: Svelte Runes | Dexie Quick Ref

7.4 KiB Raw Blame History