Docs: Add CLAUDE.md project context file for AI agent coordination
Project-specific context file for Claude Code containing: - Critical privacy/business rules (IDAA, Journals) - Mandatory workflows and tech stack - API patterns and key documentation references - Active issues tracking Complements global ~/.claude/CLAUDE.md with SvelteKit-specific guidance.
This commit is contained in:
Scott Idem
120
CLAUDE.md
Normal file
120
CLAUDE.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user