From b46f41e7bb3e8813fe63c685f87aa5838844e414 Mon Sep 17 00:00:00 2001 From: Michael Chihlas Date: Thu, 5 Mar 2026 20:04:59 -0500 Subject: [PATCH] docs: update CLAUDE.md with session learnings - Bump migration count to 49 - Add chat conclusion and survey management to recently completed - Add lessons #41-43: assistant chat state pattern, public page fetch pattern, EmailService pattern Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e116c81a..0446a7bf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,23 +47,25 @@ When adding new pages/components: use "ResolutionFlow" branding, ice-cyan gradie ## Current State - **Phase:** Phase 2.5 - Step Library Foundation (In Progress) -- **Backend:** Complete (25+ API endpoints, 100+ integration tests) +- **Backend:** Complete (35+ API endpoints, 100+ integration tests) - **Frontend:** Core features complete, Tree Editor functional -- **Database:** PostgreSQL with Docker, 30+ migrations +- **Database:** PostgreSQL with Docker, 49 migrations - **Detailed status:** [CURRENT-STATE.md](CURRENT-STATE.md) ### What's In Progress -- Procedural flows reusability and run lifecycle improvements (Phase 2) - Step Library Frontend UI ### Recently Completed -- Maintenance flows: `maintenance` tree_type, batch session launch, saved target lists, APScheduler cron scheduling, maintenance detail page -- Session sharing: ShareSessionModal, SharedSessionPage, MySharesPage, share links with copy/manage -- Procedural editor UX: section headers as step type, "More Options" collapsible, URL intake field, tag input improvements -- Type-aware routing: centralized `getTreeNavigatePath` helper, procedural resume support, safety redirects -- Export improvements (Phases A-C): step cutoff, summary block, detail levels, editable preview, sensitive data redaction +- AI chat session conclusion: outcome tracking, AI-generated ticket summaries, resume flow +- Survey completion: email-to-self, thank-you page, admin read/unread/archive/delete management +- Survey system: public survey page, admin invite tracking, response viewer with CSV export +- Email verification: tokens, banner, admin toggle (platform setting) +- AI assistant: in-session copilot panel, standalone chat with RAG +- Slate & Ice aesthetic redesign: glassmorphism, brand fonts, orchestrated animations +- Account management: profile settings, delete/leave/transfer, chat retention +- Maintenance flows: batch session launch, saved target lists, APScheduler scheduling --- @@ -94,7 +96,7 @@ patherly/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI entry point -│ │ ├── api/endpoints/ # Route handlers (auth, trees, sessions, admin, steps, etc.) +│ │ ├── api/endpoints/ # Route handlers (auth, trees, sessions, admin, steps, survey, copilot, assistant_chat) │ │ ├── api/deps.py # Auth dependencies │ │ ├── api/router.py # Route registration │ │ ├── core/ # config, database, permissions, security, audit, rate_limit @@ -112,6 +114,7 @@ patherly/ │ │ ├── store/ # Zustand stores (auth, treeEditor, proceduralEditor, userPreferences) │ │ └── types/ # TypeScript interfaces │ └── tailwind.config.js +├── docs/plans/archive/ # Archived design/impl docs (pre-March 2026) ├── CLAUDE.md # This file ├── CURRENT-STATE.md # Detailed feature status ├── LESSONS-LEARNED.md # (Deprecated — consolidated into CLAUDE.md) @@ -304,8 +307,18 @@ navigate(`/trees/${newTree.id}/edit`) **37. First deployed user needs manual admin promotion:** New users default to `engineer` role. Promote via SQL: `UPDATE users SET role = 'admin' WHERE email = '...';` then re-login for new JWT. +**39. Platform settings for feature toggles:** Use `SettingsManager.get("key", db, default=True)` to gate features. Add toggle in `admin/SettingsPage.tsx` (same pattern as `maintenance_mode`). Frontend can check status via a lightweight GET endpoint without auth. + +**40. Survey public routes:** `SurveyPage` is a public route (no auth). Survey invite tokens are passed as `?token=` query param. Add public pages at top level in `router.tsx` alongside `/login`. + **38. Alembic migrations MUST use sequential numbered prefixes:** Check `backend/alembic/versions/` for the highest numbered migration and use the next number. Format: `XXX_descriptive_name.py` (e.g., `040_add_whatever.py`). NEVER use auto-generated revision IDs like `0f1ca2af3647`. Always pass `--rev-id` flag: `alembic revision --autogenerate -m "desc" --rev-id=040`. +**41. Assistant chat uses local React state, not a Zustand store:** `AssistantChatPage.tsx` manages `chats`, `activeChatId`, `messages`, `input`, `loading` as `useState`. The `aiChatStore.ts` is for the AI Chat Builder (tree generation), NOT the standalone assistant. Don't look for a store when modifying assistant chat. + +**42. Public pages use raw `fetch()`, not `apiClient`:** Survey, shared sessions, and other no-auth pages call the API directly via `fetch()` with `${import.meta.env.VITE_API_URL || 'http://localhost:8000'}/api/v1/...`. Don't use `apiClient` — it requires auth tokens and uses relative paths. + +**43. Adding new email types:** Add static async method to `EmailService` in `core/email.py`. Pattern: check `settings.email_enabled`, import `resend`, build HTML string, call `resend.Emails.send()`, return `bool`. Always fire-and-forget from endpoints (log errors, don't fail the request). + --- ## RBAC & Permissions