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)

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