OSIT-AE-App-Svelte/documentation/AE_UI_Journals_module_update_2026.md

Aether Journals UI Update (2026)

Status: 🚧 Stuck on Phase 4 (Security/Encryption Blockers) Last Updated: 2026-01-14 Primary Agent: Frontend SvelteKit Agent

1. Project Overview

This document outlines the modernization of the Journals module UI in the SvelteKit frontend (aether_app_sveltekit). The primary goals are to fully leverage the generic V3 API architecture and introduce high-velocity productivity features for journal management.

Context: The backend transition to the generic api_crud_v3 router is complete. Custom legacy routers have been removed. The frontend must now fully align with this pattern and provide a frictionless user experience.

---

2. Core Objectives

🎯 Primary Goals

1. V3 API Verification: Ensure all CRUD operations utilize the generic api_crud_v3 endpoints (Verified).
2. Quick Add UI: Implement a specialized interface for rapid, friction-free entry creation.
3. Append/Prepend UI: Allow users to quickly add text to the beginning or end of existing entries without full edit mode.
4. Interop & Portability: Robust import/export logic for Markdown/HTML (Nextcloud Notes compatibility).
5. Security Hardening: Review and harden client-side encryption logic (BLOCKED).

---

3. Technical Architecture

Backend (Completed)

• Router: api_crud_v3 (Generic)
• Definitions: app/ae_obj_types_def.py -> app/object_definitions/journals.py
• Endpoints: /v3/crud/journal/... and /v3/crud/journal_entry/...

Frontend (In Progress)

• State Management: src/lib/ae_journals/ae_journals_stores.ts
• Local Storage: Dexie.js (db_journals)
• API Client: src/lib/api/api.ts -> get_ae_obj_v3
• Export Engine: Centralized templates in src/lib/ae_journals/ae_journals_export_templates.ts.

---

4. Feature Specifications

⚡ Quick Add (Complete)

• Component: src/routes/journals/ae_comp__journal_entry_quick_add.svelte
• Behavior: Creates a new journal_entry attached to the active journal without leaving the list view.

📝 Append / Prepend (Complete)

• Interaction: Fast text injection via AeCompModalJournalEntryAppend.
• Logic: Updates entry content without full editor state overhead.

🔄 Interop (Markdown/HTML) (Complete)

• Goal: Bulk export/import for data portability.
• Templates: Standard, Personal Log, Amazon Vine.

---

5. Implementation Plan

Phase 1: Foundation (Done)

• Backend cleanup (remove legacy routers).
• Verify frontend uses V3 API (ae_journals__journal.ts).

Phase 2: Rapid Entry (Complete)

• Create ae_comp__journal_entry_quick_add.svelte.
• Integrate Quick Add into +page.svelte.

Phase 3: Content Manipulation & Portability (Complete)

• Implement Append/Prepend logic.
• Implement Bulk Export/Import system.
• Establish centralized Export Template engine.

Phase 4: Polish & Security (ACTIVE BLOCKER)

• Implement Auto-Save toggle and visual status indicators.
• Solidify E2EE passcode system for Journals and Entries.
• BLOCKER: Decryption workflow is currently unstable due to Svelte 5 reactivity loops.
• Audit encryption flow for Quick Added and Imported entries.
• Integrate Outbound Email sharing.

---

⚠️ Technical Blocker: The "Decryption-Sync" Loop

The Issue

The component is suffering from a Reactive Feedback Loop between decryption, auto-save, and background IDB refreshes.

1. Decrypting content triggers a change in tmp_entry_obj.content.
2. The Auto-Save effect sees this as a manual user edit and saves to the database.
3. Dexie LiveQuery detects the DB update and refreshes the object.
4. The Sync effect resets the entry to its encrypted state (from DB).
5. The Auto-Decryption effect fires again, starting the loop over.

What we tried:

• is_processing flags: Attempted to block reactivity during decryption.
• untrack(): Attempted to isolate store updates.
• Reference Sync: Attempted to update orig_entry_obj simultaneously with decryption to fool the change detector.
• Direct Store Updates: Switching from property assignment to journals_sess.update() to fix Svelte 5 notification failures.

Future Fix Ideas:

1. Native Svelte 5 State: Refactor journals_sess from a Svelte 4 Writable to a class using $state.
2. Logic Extraction: Move decryption logic into a non-reactive class/helper to isolate side effects from the UI render cycle.
3. Hash Comparison: Use content hashes for change detection instead of string comparisons to avoid whitespace/normalization loops.