From 3b0f036077e20888b18b4428f823b21177b64d66 Mon Sep 17 00:00:00 2001 From: chihlasm Date: Tue, 3 Feb 2026 01:59:42 -0500 Subject: [PATCH] Update CLAUDE.md with Phase 2.5 progress - Document completed Issues #3, #5, #6, #7 - Add Step Categories and Step Library API docs - Add userPreferencesStore and SettingsPage to structure - Add step_category.py and step_library.py models - Document ALLOW_RAILWAY_ORIGINS env var for PR CORS - Note VITE_API_URL must include https:// prefix - Add /debug/cors endpoint documentation - Update roadmap with Phase 2.5 progress Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 76 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 769095c4..97213db4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # CLAUDE.md - Patherly Project Context > **Purpose:** This file provides Claude Code with essential context for working on the Patherly project. -> **Last Updated:** February 2, 2026 +> **Last Updated:** February 3, 2026 --- @@ -19,9 +19,9 @@ ## Current State -- **Phase:** Phase 2 - Tree Editor (In Progress) -- **Backend:** Complete (18 API endpoints, 40+ integration tests, all passing) -- **Frontend:** Core features complete, Tree Editor functional +- **Phase:** Phase 2.5 - Step Library Foundation (In Progress) +- **Backend:** Complete (20+ API endpoints, 40+ integration tests, all passing) +- **Frontend:** Core features complete, Tree Editor functional, Settings page added - **Database:** PostgreSQL with Docker (container name: `patherly_postgres`) ### What's Complete @@ -42,9 +42,28 @@ - Cascade delete for subfolders - Team admin role with scoped permissions - Filter trees by category, tags, and folders +- **User Preferences (Issue #3):** + - Settings page at `/settings` + - Default export format preference (persisted in localStorage) + - Theme toggle integrated in Settings +- **Step Categories (Issue #5):** + - Database table with 10 seeded global categories + - Full CRUD API at `/api/v1/step-categories` + - Team scoping support (global + team-specific) +- **Step Library Schema (Issue #6):** + - `step_library` table for reusable troubleshooting steps + - `step_ratings` table for user ratings/reviews + - `step_usage_log` table for tracking verified use + - Support for decision/action/solution step types + - Visibility levels: private, team, public +- **Step Library API (Issue #7):** + - Full CRUD at `/api/v1/steps` + - Full-text search endpoint + - Popular tags endpoint + - Rating/review system with verified use tracking ### What's In Progress -- User preferences (export format default) +- Step Library frontend UI (Phase 2.5 continuation) ### Deployment - **Production:** Railway (app.patherly.com / api.patherly.com) @@ -99,9 +118,11 @@ patherly/ │ │ │ ├── session.py # JSONB path_taken, decisions │ │ │ ├── attachment.py │ │ │ ├── invite_code.py -│ │ │ ├── category.py # TreeCategory model (NEW) -│ │ │ ├── tag.py # TreeTag model (NEW) -│ │ │ └── folder.py # UserFolder model (NEW) +│ │ │ ├── category.py # TreeCategory model +│ │ │ ├── tag.py # TreeTag model +│ │ │ ├── folder.py # UserFolder model +│ │ │ ├── step_category.py # StepCategory model (NEW) +│ │ │ └── step_library.py # StepLibrary, StepRating, StepUsageLog (NEW) │ │ └── schemas/ # Pydantic schemas │ ├── alembic/ # Database migrations │ ├── scripts/ @@ -125,7 +146,8 @@ patherly/ │ │ ├── store/ │ │ │ ├── authStore.ts # Zustand auth state │ │ │ ├── themeStore.ts # Dark/light theme -│ │ │ └── treeEditorStore.ts # Tree editor state (immer + zundo) +│ │ │ ├── treeEditorStore.ts # Tree editor state (immer + zundo) +│ │ │ └── userPreferencesStore.ts # User preferences (NEW) │ │ ├── components/ │ │ │ ├── common/ # Modal, ErrorBoundary, ThemeToggle │ │ │ ├── layout/ # AppLayout, ProtectedRoute @@ -139,7 +161,8 @@ patherly/ │ │ │ ├── TreeNavigationPage.tsx # Core feature │ │ │ ├── TreeEditorPage.tsx │ │ │ ├── SessionHistoryPage.tsx -│ │ │ └── SessionDetailPage.tsx +│ │ │ ├── SessionDetailPage.tsx +│ │ │ └── SettingsPage.tsx # User preferences (NEW) │ │ ├── types/ # TypeScript interfaces │ │ └── lib/utils.ts # cn() utility for Tailwind │ ├── package.json @@ -352,7 +375,7 @@ PUT /api/v1/tags/trees/{id} - Replace tree's tags DELETE /api/v1/tags/trees/{id}/{slug} - Remove tag from tree ``` -### Folders (NEW) +### Folders ``` GET /api/v1/folders - List user's folders (includes parent_id) POST /api/v1/folders - Create folder (supports parent_id for subfolders) @@ -370,6 +393,32 @@ DELETE /api/v1/folders/{id}/trees/{tree_id} - Remove tree from folder - Same folder name allowed under different parents - Moving folders validates cycle prevention +### Step Categories (NEW) +``` +GET /api/v1/step-categories - List categories (global + user's team) +POST /api/v1/step-categories - Create category (admin/team_admin) +GET /api/v1/step-categories/{id} - Get category +PUT /api/v1/step-categories/{id} - Update category +DELETE /api/v1/step-categories/{id} - Soft delete category +``` + +### Step Library (NEW) +``` +GET /api/v1/steps - List steps (filters: visibility, category_id, tags, min_rating, step_type, sort_by) +POST /api/v1/steps - Create step +GET /api/v1/steps/{id} - Get step details +PUT /api/v1/steps/{id} - Update step (owner/admin) +DELETE /api/v1/steps/{id} - Soft delete step (owner/admin) +GET /api/v1/steps/search - Full-text search (?q=query) +GET /api/v1/steps/tags/popular - Popular tags list + +# Rating endpoints +POST /api/v1/steps/{id}/rate - Rate a step (1-5 stars + optional review) +PUT /api/v1/steps/{id}/rate - Update your rating +DELETE /api/v1/steps/{id}/rate - Remove your rating +GET /api/v1/steps/{id}/reviews - Get reviews for a step +``` + ### Sessions ``` GET /api/v1/sessions - List user's sessions @@ -441,6 +490,7 @@ interface Decision { - **Auth:** `useAuthStore` - Zustand with localStorage persistence - **Theme:** `useThemeStore` - Dark/light/system preference - **Tree Editor:** `useTreeEditorStore` - Zustand + immer + zundo (undo/redo) +- **User Preferences:** `useUserPreferencesStore` - Zustand with localStorage persistence (export format default) ### Component Guidelines - Use `cn()` from `@/lib/utils` for Tailwind class merging @@ -508,10 +558,16 @@ const response = await api.get('/api/v1/trees') ## Future Roadmap -### Phase 2.5 (Planned) -- Personal tree branching (add custom steps during sessions) -- Step library with categories, tags, and ratings -- Tree forking and sharing +### Phase 2.5 (In Progress) +- ✅ Step Categories database and API +- ✅ Step Library database schema (step_library, step_ratings, step_usage_log) +- ✅ Step Library CRUD API with search and ratings +- ✅ User Preferences (Settings page, export format default) +- 🔲 Step Library browser component (frontend) +- 🔲 Add Custom Step button in tree navigation +- 🔲 Custom step creation modal +- 🔲 Personal tree branching (add custom steps during sessions) +- 🔲 Tree forking and sharing ### Phase 3 (Planned) - File attachments (screenshots, logs) @@ -580,6 +636,7 @@ Railway creates isolated preview environments for each pull request. - Switch to the PR environment - Click on each service → Settings → Networking → Generate Domain 6. **Set `VITE_API_URL`** on frontend service to point to the PR backend URL + - **IMPORTANT:** Must include `https://` prefix (e.g., `https://patherly-patherly-pr-24.up.railway.app`) 7. Redeploy frontend if needed 8. Test at preview URLs 9. Merge PR → auto-deploys to production @@ -589,12 +646,16 @@ Railway creates isolated preview environments for each pull request. - PR environments inherit from `production` base environment - `REQUIRE_INVITE_CODE=true` is inherited (create invite codes in PR DB if needed) - `DATABASE_URL` is auto-provided for isolated PR database +- `ALLOW_RAILWAY_ORIGINS=true` (shared variable) - enables CORS for all `*.up.railway.app` origins **Notes:** - Each PR gets a fresh database - no existing users/trees - Migrations run automatically via `releaseCommand` - Domains must be generated manually for each PR service +**Debug Endpoints (available in PR environments):** +- `/debug/cors` - Check CORS configuration (allow_railway_origins, cors_mode) + --- ## Contact