refactor(events): harden V3 String-Only ID vision and fix Session Alert store error
- Standardized Event module logic files to strictly use random string IDs, ensuring frontend consistency and avoiding 'Integer Trap' 404s. - Refactored 'ae_comp__event_session_alert.svelte' to accept a plain object instead of a store/observable, resolving the 'store_invalid_shape' error in list loops. - Updated all callers of the alert component to pass unwrapped session objects. - Cleaned up event-related UI components to remove redundant '_random' field lookups and align with V3 CRUD patterns. - Updated project metadata (GEMINI.md, TODO.md) to reflect the new memory structure and latest hardened state.
This commit is contained in:
Scott Idem
187
GEMINI.md
187
GEMINI.md
@@ -1,94 +1,139 @@
|
||||
# Aether (AE) SvelteKit Application
|
||||
# Gemini Agent Context: 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.
|
||||
> **Template Version:** 1.2 (2026-01-26)
|
||||
> **Purpose:** Standardized memory structure for all Aether Agents.
|
||||
> **Structure:** Inverted Pyramid (Foundational -> Strategic -> Tactical -> Reference).
|
||||
|
||||
## 🎯 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.
|
||||
## 1. 💾 Long Term Memory (System & Facts)
|
||||
*This section contains the "Universal Truths" that rarely change. It grounds the agent in the user's reality.*
|
||||
|
||||
## 🏗️ Architecture & Standards
|
||||
### 🤖 Agent Identity & Role
|
||||
- **Agent Name:** mcp_agent (SvelteKit Frontend)
|
||||
- **Primary Role:** Frontend UI/UX Development & Svelte 5 Migration.
|
||||
- **Scope:** `aether_app_sveltekit/`, Svelte components, Dexie stores, and V3 API integration.
|
||||
|
||||
### 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.
|
||||
### 👤 User Profile
|
||||
- **User:** Scott Idem (`scott`)
|
||||
- **Organizations:**
|
||||
- **One Sky IT (OSIT):** Professional/Business context.
|
||||
- **Danger Zone (DgrZone):** Personal/Home context.
|
||||
- **Aether Platform (AE):** Scott's (One Sky IT) platform developed for OSIT.
|
||||
- **Preferences:**
|
||||
- **Editor:** `vim` (Terminal), VS Code (GUI).
|
||||
- **Communication:** Direct, concise, professional CLI tone.
|
||||
- **Safety:** "Recycle Bin" (`~/tmp/gemini_trash`) instead of `rm`. Explain destructive actions first.
|
||||
- **Hardware/OS:**
|
||||
- **Host:** Linux System
|
||||
- **OS:** Linux
|
||||
|
||||
### 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.
|
||||
### 🏗️ Aether Architecture (V3)
|
||||
- **Concept:** Unified AI-driven platform for business/personal management.
|
||||
- **Frontend:** SvelteKit + Tailwind 4 + Skeleton UI + Dexie.js (Local-first).
|
||||
- **Backend:** FastAPI + Pydantic V1 + SQLAlchemy + MariaDB (Remote).
|
||||
- **Orchestration:** Docker Compose (via `aether-ops` extension).
|
||||
- **Core Principle:** "Agent Bridge" - Distributed agents coordinating via file-based messaging.
|
||||
|
||||
### 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.
|
||||
#### 🎨 Frontend 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.
|
||||
- **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.
|
||||
- **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 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 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` handles data shaping and computed fields.
|
||||
3. **Cache:** Save cleaned data to IndexedDB via `db_save_ae_obj_li__ae_obj`.
|
||||
|
||||
### 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`.
|
||||
### 📜 Core Protocols
|
||||
- **RAR Protocol:** Request -> Ack -> Result (for inter-agent tasks).
|
||||
- **Bite-Sized Data:** Avoid monolithic files (>1MB). Split data into atomic chunks (e.g., `objects/*.json`).
|
||||
- **Fail Fast & Transparently:** Revert immediately if a change breaks the system. API returns 500 on hard errors.
|
||||
- **V3 CRUD Paradigm:** JSON metadata via `/v3/crud/`, binary actions via `/v3/action/`.
|
||||
- **Project Mandates:**
|
||||
- **Fast is slow. Slow is fast.** Deliberate, careful progress.
|
||||
- **Commit early and often.** Test before committing.
|
||||
- **Trust but verify.** Verify tool outputs and assumptions.
|
||||
|
||||
### 🛡️ Security & Secrets Guardrails
|
||||
- **Secrets:** NEVER read or display content from `.env` files unless explicitly debugging configuration logic.
|
||||
- **Logging:** Do not include MariaDB passwords, API keys, or personal tokens in `ae_log_work` or commit messages.
|
||||
- **PII:** Scrub personally identifiable information if sharing logs or data across the bridge.
|
||||
|
||||
### 🧪 Verification & Quality
|
||||
- **Pre-Flight:** Verify `git status` before modification.
|
||||
- **Compile Check:** Perform syntax checks and basic compile verification before finalizing any code change.
|
||||
- **Tooling:**
|
||||
- `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.
|
||||
|
||||
### 📝 Git & Coordination
|
||||
- **Atomic Commits:** Stage related changes; avoid "megacommit" bloat.
|
||||
- **Intent-Based Messages:** Focus on "Why" and "Strategic Intent".
|
||||
- **UE-AE-01 Vision:** Unified agent with total system awareness across MariaDB, FastAPI, SvelteKit, and Nginx.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tooling & Orchestration
|
||||
## 2. 🗓️ Near Term Memory (Strategic Context)
|
||||
*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"*
|
||||
|
||||
### 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.
|
||||
### 📩 In-Flight RAR Requests
|
||||
*Track active inter-agent tasks here to ensure follow-up.*
|
||||
- [ ] **[Recipient Agent]**: [Description of request] (Sent: [YYYY-MM-DD])
|
||||
|
||||
### 🎯 Strategic Goals (Current Sprint)
|
||||
- **Primary:** Performance Sprint & Journals Standardization.
|
||||
- **Secondary:** V3 API Migration and System Health Stability.
|
||||
|
||||
### 🚧 Active Workstreams
|
||||
- **[Hydration Optimization]:** Implemented SWR pattern and non-blocking layouts to eliminate "white page" delays.
|
||||
- **[Service Worker]:** Re-enabled registration and implemented robust asset caching.
|
||||
- **[Native Bridge]:** Phase 5 AppleScript handlers for macOS (PowerPoint/Keynote).
|
||||
- **[Telemetry]:** Modern dashboard in Launcher Config with visual CPU/RAM gauges.
|
||||
- **[Journals Module]:** Standardized naming (`ae_comp__*`), normalized props to snake_case, and unified icons.
|
||||
|
||||
### 🧠 Recent Learnings & Decisions
|
||||
- **SWR Pattern:** Crucial for eliminating page load delays in Sites, Events, and Journals.
|
||||
- **Quiet Logs:** Silenced noisy `AbortError` and `NetworkError` in background fetches to reduce noise.
|
||||
- **Details Toggle:** Optimized Event Session list by deferring expensive sub-components.
|
||||
- **CodeMirror Fix:** Resolved line-wrapping issues in editors.
|
||||
|
||||
---
|
||||
|
||||
## 📂 Modules Overview
|
||||
## 3. 🧠 Short Term Memory (Session Context)
|
||||
*This section is the "Scratchpad" for the current interaction. It is cleared or summarized often.*
|
||||
|
||||
### 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).
|
||||
- **Status:** Idle / Task Complete.
|
||||
- **Last Action:** Logged work for v1.2 template standardization across the ecosystem.
|
||||
- **Current Blocker:** None.
|
||||
- **Immediate Next Step:** Await next user instruction.
|
||||
|
||||
---
|
||||
|
||||
## 📝 Development History (Consolidated)
|
||||
## 4. 📂 Reference: Directory & Whitelist
|
||||
*Low-density reference data. Keep at the bottom to avoid cluttering the prompt's "hot zone".*
|
||||
|
||||
### Launcher Phase 5 & Performance Sprint (2026-01-26)
|
||||
- **Hydration Optimization:** Implemented Stale-While-Revalidate (SWR) pattern and non-blocking layouts across Sites, Events, and Journals to eliminate "white page" delays.
|
||||
- **Service Worker:** Re-enabled automatic registration and implemented robust asset caching using SvelteKit metadata.
|
||||
- **Native Bridge:** Implemented Phase 5 AppleScript handlers for PowerPoint and Keynote on macOS.
|
||||
- **Telemetry:** Built a modern dashboard in Launcher Config with visual CPU/RAM gauges and animated sync status.
|
||||
- **API Hardening:** Silenced noisy `AbortError` and `NetworkError` logs in background fetches.
|
||||
### 🛡️ File Whitelist
|
||||
- `~/tmp`, `~/Downloads`, `~/temp`, `~/agents_sync`
|
||||
|
||||
### 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**.
|
||||
...
|
||||
---
|
||||
### 🗺️ Standard Directory Map
|
||||
- **`src/lib/ae_api/`**: API V3 standard helpers.
|
||||
- **`src/lib/ae_journals/`**: Journals feature module.
|
||||
- **`src/lib/types/ae_types.ts`**: Unified TypeScript interfaces.
|
||||
|
||||
## 🧠 Session Context (2026-01-26)
|
||||
- **Status:** Performance Sprint & Journals Standardization Complete.
|
||||
- **Recent Actions:**
|
||||
- Eliminated page load delays via SWR and non-blocking background refreshes.
|
||||
- Standardized Journals module: renamed all components to `ae_comp__*`, normalized props to snake_case, and unified icons under `lucide-svelte`.
|
||||
- Fixed line-wrapping issues in both plain and CodeMirror editors.
|
||||
- Optimized Event Session list rendering with a "Details" toggle to defer expensive sub-components.
|
||||
- Hardened Service Worker and suppressed aborted fetch logs.
|
||||
- Finalized Native Launcher Phase 5 automation and Telemetry UI.
|
||||
- **Pending Tasks:**
|
||||
- [ ] Refactor `get_device_config` to be non-blocking in root layout.
|
||||
- [ ] Audit IDAA pages for reported issues.
|
||||
- [ ] Restore Exhibit Search functionality.
|
||||
- [ ] Build standalone Payload Validation tool.
|
||||
### 📦 Modules Overview
|
||||
- **Core:** Identity (`accounts`, `people`, `users`), Infrastructure (`sites`, `site_domains`), Storage (`hosted_files`).
|
||||
- **Feature:** Events (Badge printing, QR), Journals (Notes, AI), IDAA (Logistics, Jitsi).
|
||||
|
||||
## 🔗 Resources
|
||||
### 🔗 Resources
|
||||
- **Reference Stubs:** `agents_sync/technical/references/` (Svelte 5, Dexie, FastAPI).
|
||||
- **Official Docs:** [Svelte Runes](https://svelte.dev/blog/runes) | [Dexie Quick Ref](https://dexie.org/docs/API-Reference#quick-reference)
|
||||
- **Official Docs:** [Svelte Runes](https://svelte.dev/blog/runes) | [Dexie Quick Ref](https://dexie.org/docs/API-Reference#quick-reference)
|
||||
Reference in New Issue
Block a user