Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
32002fe6bd87f3d7ccc2fa3ef6e0a29badde2664
OSIT-AE-App-Svelte/GEMINI.md
Scott Idem 8fae3aa89a Fix(ServiceWorker): Mitigate persistent TypeError by disabling auto-registration 
- Mitigation: Disabled `serviceWorker.register` in `svelte.config.js` to stop the loop of `TypeError` during script evaluation.
- Debug Tool: Preserved the `fix-sw` cache clearing utility by moving it to `src/routes/testing/fix-sw/+page.svelte` for future investigation.
- Service Worker: Simplified `src/service-worker.js` to a minimal "Hello World" state and removed the problematic `.ts` version.
- Cleanup: Minor formatting adjustment in `ae_events_functions.ts`.
- Docs: Updated `TODO.md` and `GEMINI.md` to reflect the mitigation and planned follow-up.
2026-01-21 16:49:33 -05:00

8.9 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

  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)

Hardening & Search Restoration (2026-01-21)

  • Critical Learning: V3 Search Body Strictness: The search_query POST body is extremely strict. Adding non-mapped fields (e.g., event_location_name) triggers HTTP 400 "Unauthorized search field" errors.
  • Critical Learning: Preservation of Business Logic: Specialized search parameters (ft_qry, lk_qry, and_qry) are handled by custom backend logic and MUST be passed as URL query parameters (serialized JSON), not in the search body. These are the "sacred" rules of the Aether system and must not be "cleaned up" during modernization.
  • Critical Learning: Barrel Cleanup Order: Barrel files (api.ts, ae_core_functions.ts) must be updated to remove legacy exports before deleting code from source files to prevent build-time SyntaxError crashes.
  • V3 API Hardening: Updated search_ae_obj_v3 to correctly serialize all object-type params into the URL, enabling complex filtering like ft_qry.
  • Event Session Search: Restored full business logic mapping for session search, including ft_qry, lk_qry, and and_qry.
  • Service Worker: Fixed 404 on /manifest.json path in app.html and restored service-worker.js to standard SvelteKit state to resolve evaluation errors.
  • Service Worker Mitigation: Disabled automatic service worker registration in svelte.config.js to resolve persistent TypeError during script evaluation. Moved debugging tool to src/routes/testing/fix-sw/.

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 in New Issue View Git Blame Copy Permalink