OSIT-AE-App-Svelte/GEMINI.md

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

1. Fetch: API Function calls the V3 endpoint.
2. Process: Dedicated process_ae_obj__*_props function handles data shaping, parent ID injection, and computed fields.
3. 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)

Launcher Phase 4 & Hardening (2026-01-26)

• Heartbeat Engine: Implemented V3-compliant heartbeat and room refresh cycles.
• UI Integration: Migrated heartbeat/sync status from "Secret Monitor" to formal Launcher Config Drawer.
• Timezone Fix: Resolved "future time" issue by standardizing on UTC ISO strings and removing manual 'Z' suffixing in ae_events__event_device.ts.
• MySQL Compatibility: Fixed Error 1292 by formatting heartbeats to YYYY-MM-DD HH:mm:ss using ae_util.iso_datetime_formatter.
• API V3 Hardening: Implemented auto-serialization for _json fields in V3 CRUD helpers to prevent 'str type expected' validation failures.
• Singleton Consolidation: Moved LauncherBackgroundSync to the root launcher layout to ensure a single execution loop.
• IDAA Jitsi Reports: Fixed a TypeError in report processing and restored filtering logic. Added explicit x-account-id headers to resolve 403 Forbidden errors.

Hardening & Error Reduction Sprint (2026-01-22)

• Error Reduction: Systematically cleared ~133 svelte-check errors (from 372 to 239) across the entire application.
• Type Hardening: Resolved ambient module errors in analytics.svelte, fixed onsubmit mismatches in file uploads, and hardened CodeMirror element casting.

---

🧠 Session Context (2026-01-26)

• Status: Phase 4 Implementation Complete & Verified.
• Recent Actions:
  • Integrated heartbeat/sync observability into formal Config UI.
  • Fixed ReferenceError and illegal variable name ($events_sess) errors.
  • Resolved persistent 400/403 errors in Jitsi and Heartbeat logic.
• Pending Tasks:
  • Implement Phase 5 AppleScript handlers for PowerPoint/Keynote.
  • Build Telemetry Dashboard in Launcher Config (CPU/RAM visuals).

🔗 Resources

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