chihlasm/resolutionflow
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: update CLAUDE.md with maintenance flows learnings

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
chihlasm
2026-02-17 18:36:22 -05:00
parent 1b1ecf13ca
commit dbe0e9e5b3
1 changed files with 16 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
CLAUDE.md
View File

@@ -1,6 +1,6 @@
# CLAUDE.md - Patherly / ResolutionFlow Project Context
> **Last Updated:** February 15, 2026
> **Last Updated:** February 17, 2026
---
@@ -25,8 +25,8 @@
- **Brand assets:** `brand-assets/` (source SVGs + brand-guide.html), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon)
- **CSS utilities:** `text-gradient-brand`, `bg-gradient-brand`, `bg-gradient-brand-hover` (defined in `tailwind.config.js` and `index.css`)
- **Layout:** App shell with persistent sidebar + top bar + main content (CSS Grid). See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md)
- **Navigation:** Sidebar nav with type sub-items (All Flows → Troubleshooting / Projects). Pinned flows section for quick access. NO workspace switcher. See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md)
- **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. `tree_type` column values unchanged in DB.
- **Navigation:** Sidebar nav with type sub-items (All Flows → Troubleshooting / Projects / Maintenance). Pinned flows section for quick access. NO workspace switcher. See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md)
- **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. Maintenance flows are called "Maintenance" in the UI. `tree_type` column values unchanged in DB.
- **Rebrand guide:** [REBRAND-IMPLEMENTATION-GUIDE.md](REBRAND-IMPLEMENTATION-GUIDE.md)
**Component styling rules:**
@@ -59,6 +59,7 @@ When adding new pages/components: use "ResolutionFlow" branding, purple gradient
### 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
@@ -74,6 +75,7 @@ When adding new pages/components: use "ResolutionFlow" branding, purple gradient
- **Migrations:** Alembic
- **Auth:** JWT (python-jose) + bcrypt, refresh token rotation (JTI-based)
- **Validation:** Pydantic v2
- **Scheduling:** APScheduler 3.x (async, in-process with FastAPI lifespan) + croniter + pytz
### Frontend
- **Framework:** React 19 + Vite + TypeScript
@@ -177,6 +179,10 @@ cd backend && pip install httpx && python -m scripts.seed_trees
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api/docs
### Test Users (seeded via `scripts/seed_test_users.py`)
- All share password: `TestPass123!`
- `admin@resolutionflow.example.com` (super_admin), `teamadmin@resolutionflow.example.com` (team_admin), `engineer@resolutionflow.example.com` (engineer), `pro@resolutionflow.example.com` (solo pro)
---
## Critical Lessons Learned
@@ -249,6 +255,12 @@ navigate(`/trees/${newTree.id}/edit`)
**15. Session sharing types:** `TreeSnapshot` extends `TreeStructure` but session snapshots from the API include extra fields like `tree_type`. Use `tree_snapshot?.tree_type` to determine flow type from session data.
**16. tree_type has three values:** `'troubleshooting' | 'procedural' | 'maintenance'`. Maintenance reuses the procedural execution engine. Use `PROCEDURAL_TREE_TYPES` set from `core/tree_validation.py` when checking for step-based flow types.
**17. Alembic autogenerate can be destructive:** `alembic revision --autogenerate` may generate DROP TABLE/ALTER COLUMN ops for unrelated tables (especially junction tables and tables with complex FKs). Always review generated migrations carefully. Prefer manual migrations for new tables: `alembic revision -m "desc"` then write the `upgrade()`/`downgrade()` by hand.
**18. Pydantic partial updates — use `model_fields_set`:** When a PUT/PATCH endpoint needs to distinguish "field not sent" from "field sent as null", check `data.model_fields_set` instead of `data.field is not None`. This allows clients to explicitly clear nullable fields like `description`.
---
## RBAC & Permissions
@@ -287,6 +299,7 @@ navigate(`/trees/${newTree.id}/edit`)
- **Session sharing:** `ShareSessionModal` manages share links, `SharedSessionPage` renders public/account views. Helper utils in `lib/sessionShare.ts`. Share URLs use `/shared/sessions/:token`.
- **Procedural navigation:** `ProceduralNavigationPage` handles intake forms, step-by-step execution, and resume via `location.state.sessionId`. Uses `StepChecklist`, `StepDetail`, `ProgressBar`, `CompletionSummary` components.
- **Routing helper:** Use `getTreeNavigatePath()` and `getTreeEditorPath()` from `@/lib/routing` for all tree/session navigation.
- **Account section layout:** `AccountLayout` has NO sidebar nav. Account sub-pages (categories, target-lists) are reached via link cards on `AccountSettingsPage.tsx`. New account pages: add route in `router.tsx` under `account` children + add a link card in `AccountSettingsPage`.
---