OSIT-AE-App-Svelte/CLAUDE.md

Claude Code — Project: Aether App SvelteKit

Part of: One Sky IT / Aether Platform Backend: ~/OSIT_dev/aether_api_fastapi/ via Docker

---

CRITICAL: Privacy & Business Rules

IDAA — International Doctors in Alcoholics Anonymous

• ALL IDAA content is PRIVATE. Authentication required. Never public.
• BB (Bulletin Board / Posts) — always private
• Archives — always private
• Recovery Meetings — always private
• A previous AI agent accidentally exposed IDAA BB publicly. This is a severe security failure.
• IDAA users authenticate via Novi API (Novi UUID per member) at Authenticated permission level.
• Default permission required: trusted_access or higher for IDAA module.

Journals

• Private personal data. Always authenticated. Passcode/encryption features exist.

General

• Never expose private content publicly. When in doubt — it's private.
• Code comments must explain the WHY for any non-obvious business logic. Key features have been silently broken by AI agents that didn't understand intent.

---

Mandatory Workflow

1. Before starting: Read documentation/TODO__Agents.md for active tasks
2. Before committing: Run npx svelte-check — no exceptions
3. Commits: Atomic — one component or fix per commit
4. Never delete files with rm — move to ~/tmp/gemini_trash
5. Backend coordination: Use ae_send_message or flag changes clearly

---

Tech Stack

• Framework: Svelte 5 (runes mode) + SvelteKit v2
• Styling: Tailwind CSS v4, Flowbite; Skeleton UI being phased out
• State: $state, $derived runes + Dexie.js IndexedDB (liveQuery)
• Icons: Lucide
• Editors: CodeMirror 6 (primary), Edra/TipTap (secondary)
• Markdown: marked library
• UI primitives: ShadCN (src/lib/components/ui/)
• Native/Electron bridge: src/lib/electron/electron_relay.ts via window.aetherNative

---

API (V3)

• Base: /v3/crud/{obj_type}/ for all CRUD
• Lookups: /v3/lookup/
• Search: POST /v3/crud/{obj_type}/search
• Auth headers: x-aether-api-key + x-account-id (NOT Bearer tokens)
• Permissive PATCH: add x-ae-ignore-extra-fields: true
• Guide: documentation/GUIDE__AE_API_V3_for_Frontend.md

---

Key Patterns

• Canonical reference: Journals module (src/lib/ae_journals/) — use as the pattern template
• Object files: ae_<module>__<object>.ts + <object>.editable_fields.ts
• DB: db_<module>.ts per module (Dexie instance)
• LiveQuery: lq__xyz (read-only), lqw__xyz (writable form snapshot)
• Load pattern: SWR — return Dexie cache immediately, refresh from API in background
• Component naming: ae_comp__* (route-level), ae_<module>_comp__* (module), element_* (reusable)
• Standard fields: id, id_random, code, name, enable, hide, priority, sort, group, notes, created_on, updated_on, cfg_json, data_json

---

Source Layout

src/lib/
  ae_api/         — API helpers (prefer V3)
  ae_core/        — Account, User, Person, Site, Address, Contact
  ae_events/      — Events, sessions, presenters, badges, locations, devices
  ae_journals/    — Journals (canonical/frontier model)
  ae_archives/    — Archives
  ae_posts/       — Posts + Post Comments (IDAA BB)
  ae_idaa/        — IDAA custom module
  ae_reports/     — Reporting
  elements/       — Reusable UI: V3 editor, CRUD, data store, CodeMirror
  electron/       — Native app bridge

src/routes/
  /core/          — Admin (accounts, people, sites, users, contacts)
  /events/[id]/   — Events: pres_mgmt, launcher, badges, leads, settings
  /journals/      — Journals
  /idaa/          — IDAA: archives, bb, recovery_meetings, video_conferences
  /hosted_files/  — File management
  /testing/       — Dev testing

---

Active Issues (check TODO__Agents.md for current state)

• Session/Presentation page cold-start bug (Events Pres Mgmt) — unresolved
• Sev-1: PUBLIC_AE_API_SECRET_KEY audit
• CRUD v2 retirement → V3 editor
• 403/401 error boundaries ("Session Expired" UI)

---

Key Docs

File	Purpose
documentation/TODO__Agents.md	Active task list — read first
documentation/GUIDE__Development.md	Dev SOP
documentation/GUIDE__AE_API_V3_for_Frontend.md	V3 API reference (authoritative)
documentation/GUIDE__SvelteKit2_Svelte5_DexieJS.md	Dexie + liveQuery patterns
documentation/GEMINI__Svelte_and_Me.md	Svelte 5 runes patterns
documentation/PROJECT__AE_Events_Launcher_Native_integration.md	Electron/Launcher
documentation/PROJECT__AE_Pres_Mgmt_Session_view_refactor_2026-02.md	Session bug plan