# 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/agents_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)

- Sev-1: `PUBLIC_AE_API_SECRET_KEY` audit — see TODO__Agents.md (assessed acceptable, 2026-03-11)
- V3 CRUD migration — remaining legacy API wrappers in events/sponsorships/core (see `PROJECT__Use_AE_API_V3_CRUD_upgrade.md`)
- Style Review Phase 3 — IDAA + Pres Mgmt card polish deferred post-April 2026 conference

---

## 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_Events_Badges_Review_Print.md` | Badges — kiosk editing (Task 4.0 open) |