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

docs: Reorganize project documentation

Browse Source 
- Remove outdated documentation files
- Add ARCHITECTURE.md and BACKLOG.md
- Add docs/ folder
- Update CURRENT-STATE.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
chihlasm
2026-02-03 02:24:43 -05:00
parent 7803dc4522
commit b608b0a708
10 changed files with 1275 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

414
docs/GITHUB-ISSUES-MIGRATION.md Normal file
View File

@@ -0,0 +1,414 @@
# GitHub Issues Migration Instructions
> **For Claude Code:** Use these instructions to set up GitHub Issues for Patherly
> **Repository:** github.com/patherly/patherly
> **Date:** February 2, 2026
---
## Step 1: Create Labels
Create the following labels in the repository:
| Label | Color (hex) | Description |
|-------|-------------|-------------|
| `bug` | `d73a4a` | Something isn't working |
| `feature` | `0e8a16` | New functionality |
| `enhancement` | `a2eeef` | Improvement to existing feature |
| `documentation` | `0075ca` | Documentation updates |
| `backend` | `7057ff` | FastAPI/Python work |
| `frontend` | `fbca04` | React work |
| `database` | `b60205` | PostgreSQL/schema changes |
| `priority: high` | `d93f0b` | Do this soon |
| `priority: medium` | `fbca04` | Important but not urgent |
| `priority: low` | `c5def5` | Nice to have |
---
## Step 2: Create Milestones
| Milestone | Description | Due Date |
|-----------|-------------|----------|
| Phase 2 Completion | Tree editor polish, deployment | (leave open) |
| Phase 2.5 | Personal branching, step library | (leave open) |
| Backlog | Ideas not yet scheduled | (no due date) |
---
## Step 3: Create Issues
### Phase 2 Remaining (3 issues)
**Issue 1:**
- Title: Tree Editor Validation - required fields and orphan detection
- Labels: `feature`, `frontend`, `priority: high`
- Milestone: Phase 2 Completion
- Body:
```
Add validation to the tree editor:
- [ ] Required fields validation (name, at least one node)
- [ ] Orphan node detection (nodes not reachable from root)
- [ ] Circular reference detection
- [ ] Show validation errors before save
- [ ] Prevent save if validation fails
```
**Issue 2:**
- Title: User Preferences - export format default setting
- Labels: `feature`, `frontend`, `priority: medium`
- Milestone: Phase 2 Completion
- Body:
```
Add export format preference to user settings:
- [ ] Add "Default Export Format" dropdown in settings (Markdown/Text/HTML)
- [ ] Persist preference in localStorage
- [ ] Use preference as default in export dialog
- [ ] Dark mode toggle already complete ✅
```
**Issue 3:**
- Title: Deploy to Railway - CI/CD pipeline setup
- Labels: `feature`, `priority: high`
- Milestone: Phase 2 Completion
- Body:
```
Set up production deployment on Railway Pro:
- [ ] Configure Railway project with 3 services (PostgreSQL, backend, frontend)
- [ ] Set up environment variables
- [ ] Configure custom domains (patherly.com, api.patherly.com)
- [ ] Set up PR environments for testing
- [ ] Document deployment process
```
---
### Phase 2.5 Features (15 issues)
**Issue 4:**
- Title: Step Categories - database table and seed data
- Labels: `feature`, `backend`, `database`, `priority: high`
- Milestone: Phase 2.5
- Body:
```
Create step_categories table for organizing the step library:
- [ ] Create Alembic migration for step_categories table
- [ ] Add SQLAlchemy model
- [ ] Seed default categories (Citrix/VDI, Active Directory, Microsoft 365, Networking, etc.)
- [ ] Create API endpoints for category CRUD (admin only)
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 5:**
- Title: Step Library - database schema and migrations
- Labels: `feature`, `backend`, `database`, `priority: high`
- Milestone: Phase 2.5
- Body:
```
Create step_library table for reusable troubleshooting steps:
- [ ] Create Alembic migration
- [ ] Add SQLAlchemy model with fields: title, step_type, content (JSONB), visibility, category_id, tags, ratings aggregates
- [ ] Add indexes for search and filtering
- [ ] Add step_ratings table for user ratings/reviews
- [ ] Add step_usage_log table for "Verified Use" tracking
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 6:**
- Title: Step Library - CRUD API endpoints
- Labels: `feature`, `backend`, `priority: high`
- Milestone: Phase 2.5
- Body:
```
Create API endpoints for step library:
- [ ] GET /api/v1/steps - List steps with filters (visibility, category, tags, rating)
- [ ] GET /api/v1/steps/{id} - Get step details
- [ ] POST /api/v1/steps - Create new step
- [ ] PUT /api/v1/steps/{id} - Update step
- [ ] DELETE /api/v1/steps/{id} - Soft delete
- [ ] GET /api/v1/steps/search - Full-text search
- [ ] GET /api/v1/steps/tags/popular - Popular tags
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 7:**
- Title: Step Library - rating and review system
- Labels: `feature`, `backend`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Implement step rating and review system:
- [ ] POST /api/v1/steps/{id}/rate - Rate a step (1-5 stars + optional review)
- [ ] PUT /api/v1/steps/{id}/rate - Update rating
- [ ] DELETE /api/v1/steps/{id}/rate - Remove rating
- [ ] POST /api/v1/steps/{id}/helpful - Vote helpful (yes/no)
- [ ] GET /api/v1/steps/{id}/reviews - Get reviews
- [ ] Track "Verified Use" when step is actually used in a session
- [ ] Calculate and update aggregated ratings on step_library table
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 8:**
- Title: Add Custom Step button in tree navigation
- Labels: `feature`, `frontend`, `priority: high`
- Milestone: Phase 2.5
- Body:
```
Add ability to insert custom steps during active troubleshooting:
- [ ] Add "+ Add Custom Step" button at each decision node
- [ ] Button opens modal with two tabs: "Type My Own" and "Browse Library"
- [ ] Custom steps inserted into session only (not original tree)
- [ ] Visual indicator showing step is custom/user-added
- [ ] Custom steps included in session export
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 9:**
- Title: Custom step creation modal
- Labels: `feature`, `frontend`, `priority: high`
- Milestone: Phase 2.5
- Body:
```
Create modal for adding custom steps:
- [ ] Tab 1: "Type My Own" - form to create step (type, title, description, commands)
- [ ] Tab 2: "Browse Library" - search and select from step library
- [ ] Option to save custom step to personal library
- [ ] Validate step before insertion
- [ ] Insert step into current session
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 10:**
- Title: Step library browser component
- Labels: `feature`, `frontend`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Create UI component for browsing step library:
- [ ] Search input with full-text search
- [ ] Category filter dropdown
- [ ] Tag filter (show popular tags as chips)
- [ ] Minimum rating filter
- [ ] Sort options (recent, popular, rating)
- [ ] Step cards showing title, type, rating, usage count
- [ ] Step preview/detail modal
- [ ] Insert button to add to session
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 11:**
- Title: User Trees - database schema
- Labels: `feature`, `backend`, `database`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Create user_trees table for personal/forked trees:
- [ ] Create Alembic migration
- [ ] Fields: user_id, forked_from_tree_id, name, tree_content (JSONB), visibility, share_token
- [ ] Add session_custom_steps table to track custom steps per session
- [ ] Add indexes for user lookup and share token
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 12:**
- Title: Tree forking API endpoint
- Labels: `feature`, `backend`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Create API for forking trees:
- [ ] POST /api/v1/user-trees/fork/{tree_id} - Fork an official tree
- [ ] Deep copy tree structure to user_trees
- [ ] Track lineage (forked_from_tree_id, forked_at_version)
- [ ] Increment fork_count on original tree
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 13:**
- Title: User Trees - CRUD endpoints
- Labels: `feature`, `backend`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Create API endpoints for user tree management:
- [ ] GET /api/v1/user-trees - List user's custom trees
- [ ] GET /api/v1/user-trees/{id} - Get custom tree
- [ ] POST /api/v1/user-trees - Create new custom tree
- [ ] PUT /api/v1/user-trees/{id} - Update custom tree
- [ ] DELETE /api/v1/user-trees/{id} - Soft delete
- [ ] PUT /api/v1/user-trees/{id}/share - Update sharing settings
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 14:**
- Title: My Trees dashboard page
- Labels: `feature`, `frontend`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Create "My Trees" page for managing personal trees:
- [ ] List user's forked/custom trees
- [ ] Show original tree reference (if forked)
- [ ] Last used date, usage count
- [ ] Quick actions: start session, edit, share, delete
- [ ] Fork button on tree detail view
- [ ] Notification when original tree updated (basic)
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 15:**
- Title: Tree sharing via link
- Labels: `feature`, `frontend`, `backend`, `priority: medium`
- Milestone: Phase 2.5
- Body:
```
Allow sharing trees via link:
- [ ] Generate unique share token for tree
- [ ] GET /api/v1/shared/{share_token} - Access shared tree (no auth required)
- [ ] Share modal with visibility options (private, link, team, public)
- [ ] Copy link button
- [ ] Option to allow/disallow forking
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 16:**
- Title: Save session as custom tree
- Labels: `feature`, `frontend`, `backend`, `priority: low`
- Milestone: Phase 2.5
- Body:
```
After completing a session with custom steps, offer to save as tree:
- [ ] POST /api/v1/sessions/{id}/save-as-tree endpoint
- [ ] Prompt user after session completion (if custom steps were added)
- [ ] Create user_tree from session path + custom steps
- [ ] Allow user to name and edit before saving
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 17:**
- Title: Admin - category management UI
- Labels: `feature`, `frontend`, `priority: low`
- Milestone: Phase 2.5
- Body:
```
Admin interface for managing step categories:
- [ ] List categories with step counts
- [ ] Create new category
- [ ] Edit category name/description
- [ ] Archive category (soft delete)
- [ ] Reorder categories (display_order)
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
**Issue 18:**
- Title: Rate/review modal after using a step
- Labels: `feature`, `frontend`, `priority: low`
- Milestone: Phase 2.5
- Body:
```
Prompt users to rate steps after using them:
- [ ] After session completion, show steps used from library
- [ ] Rating modal with 1-5 stars
- [ ] Optional written review (max 500 chars)
- [ ] "Was this helpful?" quick vote
- [ ] Mark rating as "Verified Use"
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
```
---
### Known Bugs (create as closed issues for history)
**Issue 19:**
- Title: [FIXED] DateTime timezone handling causing Internal Server Errors
- Labels: `bug`, `backend`
- State: CLOSED
- Body:
```
**Problem:** Mixing timezone-aware and timezone-naive datetime objects caused errors in session completion.
**Solution:**
- Updated all SQLAlchemy models to use `DateTime(timezone=True)`
- Changed all default datetime factories to `lambda: datetime.now(timezone.utc)`
**Files affected:** All models with timestamp fields
Fixed: January 28, 2026
```
**Issue 20:**
- Title: [FIXED] bcrypt/passlib version compatibility
- Labels: `bug`, `backend`
- State: CLOSED
- Body:
```
**Problem:** Password hashing failed with newer bcrypt versions.
**Solution:** Pin bcrypt version in requirements.txt:
- bcrypt==4.0.1
- passlib[bcrypt]==1.7.4
Fixed: January 2026
```
**Issue 21:**
- Title: [FIXED] Email validation rejecting .local domains
- Labels: `bug`, `backend`
- State: CLOSED
- Body:
```
**Problem:** Seed script failed with email validation error when using `.local` TLD.
**Cause:** email-validator library correctly rejects `.local` as reserved per RFC 6761.
**Solution:** Use standard domains like `example.com` for seed/test users.
Fixed: January 29, 2026
```
**Issue 22:**
- Title: [FIXED] httpx not installed for seed scripts
- Labels: `bug`, `backend`
- State: CLOSED
- Body:
```
**Problem:** Running seed_trees.py failed with ModuleNotFoundError for httpx.
**Solution:** Install httpx before running seed scripts:
```
pip install httpx
```
Fixed: January 29, 2026
```
---
## Step 4: Verify
After creating all issues:
1. Check that labels appear correctly
2. Check that milestones have correct issues assigned
3. Verify closed issues show in closed state
---
## Notes
- Issues 4-18 are Phase 2.5 features from PHASE-2.5-PERSONAL-BRANCHING.md
- Issues 19-22 are historical bugs documented in LESSONS-LEARNED.md (create as closed)
- Long-term feature ideas are in BACKLOG.md (not GitHub Issues yet)

112
docs/archive/01-PROJECT-OVERVIEW.md Normal file
View File

@@ -0,0 +1,112 @@
# Troubleshooting Decision Tree Application
## Project Overview
### Vision
A decision tree troubleshooting application designed for MSP engineers to transform diagnostic processes into clean, professional documentation automatically.
### Core Problem
MSP engineers like Michael face constant context switching between diverse technical issues (file shares, server outages, VPN failures, Active Directory problems). Each context switch:
- Takes 15-25 minutes to regain full focus
- Creates cognitive overhead and attention residue
- Contributes to burnout (research-backed)
- Makes consistent documentation challenging
- Results in lost tribal knowledge
### Solution
An intelligent decision tree system that:
- Guides engineers through proven troubleshooting paths
- Captures decisions and notes automatically
- Generates professional ticket documentation
- Builds institutional knowledge
- Reduces cognitive load during high-stress situations
### Success Criteria
**3-Month Goal:** Michael uses this tool for 50% of his tickets
**Key Metrics:**
- Time saved per ticket
- Documentation quality improvement
- Reduction in "what did I do?" moments
- Team adoption rate
- Reduction in repeated troubleshooting attempts
### Target Users
**Primary:** Senior Systems Engineers at MSPs managing Windows Server, Active Directory, Citrix, networking equipment
**Secondary:**
- Junior engineers needing guided troubleshooting
- Onsite technicians following remote engineer instructions
- MSP teams wanting standardized procedures
### Key Differentiators
1. **Automatic documentation generation** - No separate note-taking step
2. **On-the-fly customization** - Add custom branches when encountering edge cases
3. **Learning system** - Tracks common paths, suggests optimizations
4. **Automation integration** - Execute PowerShell/scripts directly from decision nodes
5. **Knowledge hub** - Links to documentation, KB articles, tutorials at each step
6. **Team collaboration** - Controlled authorship with shared access
### Potential Market
- 30,000+ MSPs in North America alone
- Average MSP has 15-50 technical staff
- Adjacent markets: Internal IT teams, DevOps, Technical Support
### Monetization Possibilities
- **Free Tier:** Personal use, limited trees
- **Pro Tier:** Team sharing, unlimited trees, analytics
- **Enterprise:** API access, SSO, custom branding, white-label
- **Marketplace:** Community-contributed trees (revenue share)
- **Consulting:** Custom tree development services
- **Integrations:** Paid add-ons for ConnectWise, Kaseya, etc.
### Name Ideas (To Workshop)
- TroubleTree
- DecisionPath
- MSP Navigator
- FlowDoc
- DiagnosticFlow
- PathFinder
- TechTree
- TicketFlow
- DiagPath
### Competitive Landscape
**Current Solutions:**
- Static runbooks/wiki pages (not interactive)
- Flowchart tools (not designed for real-time troubleshooting)
- Ticketing system templates (limited branching logic)
- Decision tree software (too generic, not MSP-focused)
**Our Advantage:**
Purpose-built for technical troubleshooting with automation integration and automatic documentation generation.
### Technology Philosophy
- **Web-first:** Accessible anywhere, no installation
- **Progressive enhancement:** Works offline, syncs when online
- **API-driven:** Backend separate from frontend for flexibility
- **Extensible:** Plugin architecture for integrations
- **Open-source friendly:** Consider open-sourcing core, monetize integrations/hosting
### Project Status
**Current Phase:** Planning and Architecture
**Next Phase:** MVP Development (Weeks 1-3)
**Target MVP Date:** 3 weeks from project start
**Target Production Date:** 6-8 weeks from project start

581
docs/archive/02-TECHNICAL-ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,581 @@
# Technical Architecture
## System Architecture
### High-Level Architecture
```
┌─────────────────────────────────────────────────────┐
│ Frontend (React/Vue) │
│ - Tree Navigation UI │
│ - Tree Editor │
│ - Session Management │
│ - Export Functionality │
└─────────────────┬───────────────────────────────────┘
│ REST API / WebSocket
┌─────────────────┴───────────────────────────────────┐
│ Backend (Python Flask/FastAPI) │
│ - Authentication & Authorization │
│ - Tree CRUD Operations │
│ - Session Tracking │
│ - Export Generation │
│ - File Upload/Storage │
│ - Automation Execution (Future) │
└─────────────────┬───────────────────────────────────┘
│
┌─────────────────┴───────────────────────────────────┐
│ Database (PostgreSQL) │
│ - Trees (JSON) │
│ - Sessions │
│ - Users & Teams │
│ - Attachments Metadata │
└──────────────────────────────────────────────────────┘
│
┌─────────────────┴───────────────────────────────────┐
│ Object Storage (S3/MinIO) │
│ - Screenshots │
│ - Command Outputs │
│ - Logs & Attachments │
└──────────────────────────────────────────────────────┘
```
## Tech Stack
### Frontend
**Primary Choice: React**
- **Pros:** Large ecosystem, excellent offline support (PWA), familiar to most developers
- **Alternatives:** Vue.js (simpler), Svelte (faster)
- **UI Framework:** Tailwind CSS + shadcn/ui (clean, professional look)
- **State Management:** React Context + useReducer (simple) or Zustand (if needed)
- **Routing:** React Router
- **Offline:** Service Workers + IndexedDB for offline tree caching
### Backend
**Primary Choice: Python FastAPI**
- **Pros:** Modern, fast, async support, automatic API docs, matches Michael's learning path
- **Alternatives:** Flask (simpler but less performant), Django (heavier)
- **Authentication:** JWT tokens + httpOnly cookies
- **Validation:** Pydantic models
- **ORM:** SQLAlchemy 2.0 (async)
- **Migration:** Alembic
### Database
**Primary Choice: PostgreSQL**
- **Pros:** JSON/JSONB support perfect for tree storage, reliable, scalable
- **Schema Design:**
- Hybrid approach: Relational for users/sessions, JSONB for tree structure
- Full-text search for tree discovery
- Indexes on frequently queried fields
### File Storage
**Primary Choice: S3-compatible storage**
- **Development:** MinIO (self-hosted, S3-compatible)
- **Production:** AWS S3 or DigitalOcean Spaces
- **Strategy:** Pre-signed URLs for uploads, CDN for delivery
### Hosting
**Development:**
- Frontend: Local dev server (Vite)
- Backend: Local Python server
- Database: Docker PostgreSQL
**Production Options:**
1. **Simple Start:** Railway or Render (full-stack hosting)
- Cost: ~$10-20/month
- Pros: Easy deployment, managed databases
- Cons: Less control, potential scaling issues
2. **Scalable:** DigitalOcean Droplets + Managed DB
- Cost: ~$30-50/month
- Pros: More control, better performance
- Cons: More maintenance
3. **Enterprise:** AWS/Azure
- Cost: Variable
- Pros: Full feature set, enterprise compliance
- Cons: Complex, expensive
## Data Models
### Database Schema
#### Users Table
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
name VARCHAR(255) NOT NULL,
role VARCHAR(50) NOT NULL, -- admin, engineer, viewer
team_id UUID REFERENCES teams(id),
created_at TIMESTAMP DEFAULT NOW(),
last_login TIMESTAMP
);
```
#### Teams Table
```sql
CREATE TABLE teams (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
```
#### Trees Table
```sql
CREATE TABLE trees (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
description TEXT,
category VARCHAR(100), -- Citrix, Active Directory, Networking, etc.
tree_structure JSONB NOT NULL, -- The actual decision tree
author_id UUID REFERENCES users(id),
team_id UUID REFERENCES teams(id),
is_active BOOLEAN DEFAULT true,
version INTEGER DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
usage_count INTEGER DEFAULT 0
);
CREATE INDEX idx_trees_category ON trees(category);
CREATE INDEX idx_trees_team ON trees(team_id);
CREATE INDEX idx_trees_search ON trees USING gin(to_tsvector('english', name || ' ' || description));
```
#### Sessions Table
```sql
CREATE TABLE sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tree_id UUID REFERENCES trees(id),
user_id UUID REFERENCES users(id),
tree_snapshot JSONB NOT NULL, -- Copy of tree at time of use (for version tracking)
path_taken JSONB NOT NULL, -- Array of node_ids visited
decisions JSONB NOT NULL, -- Decisions made at each node with notes
started_at TIMESTAMP DEFAULT NOW(),
completed_at TIMESTAMP,
ticket_number VARCHAR(100),
client_name VARCHAR(255),
exported BOOLEAN DEFAULT false
);
CREATE INDEX idx_sessions_user ON sessions(user_id);
CREATE INDEX idx_sessions_tree ON sessions(tree_id);
CREATE INDEX idx_sessions_dates ON sessions(started_at, completed_at);
```
#### Attachments Table
```sql
CREATE TABLE attachments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID REFERENCES sessions(id),
node_id VARCHAR(100), -- Which decision node this was attached to
file_name VARCHAR(255) NOT NULL,
file_type VARCHAR(50),
file_size INTEGER,
storage_path VARCHAR(500), -- S3 key or file path
uploaded_at TIMESTAMP DEFAULT NOW()
);
```
### Tree Structure (JSON)
```json
{
"tree_id": "citrix-vda-not-registering",
"name": "Citrix VDA Not Registering",
"category": "Citrix",
"description": "Troubleshoot VDA registration issues with Delivery Controller",
"estimated_time": "10-15 minutes",
"start_node": "node_1",
"metadata": {
"author": "Michael Chihlas",
"created": "2026-01-22",
"last_updated": "2026-01-22",
"version": "1.0",
"tags": ["citrix", "vda", "registration", "delivery-controller"]
},
"nodes": {
"node_1": {
"id": "node_1",
"type": "decision",
"question": "Can you ping the VDA from the Delivery Controller?",
"help_text": "From DDC, open PowerShell and run: Test-Connection -ComputerName VDA-HOSTNAME -Count 4",
"documentation_links": [
{
"title": "Citrix VDA Communication Requirements",
"url": "https://docs.citrix.com/..."
}
],
"decision_type": "yes_no",
"allow_notes": true,
"allow_attachments": true,
"allow_custom_branch": true,
"yes": "node_2",
"no": "node_network_issue"
},
"node_2": {
"id": "node_2",
"type": "decision",
"question": "What is the status of the Citrix Virtual Desktop Agent service?",
"help_text": "Run: Get-Service -Name 'BrokerAgent' | Select-Object Status, StartType",
"decision_type": "multiple_choice",
"allow_notes": true,
"options": [
{
"label": "Running",
"value": "running",
"next": "node_check_broker"
},
{
"label": "Stopped",
"value": "stopped",
"next": "node_start_service"
},
{
"label": "Stuck in Starting/Stopping",
"value": "stuck",
"next": "node_service_stuck"
}
]
},
"node_check_broker": {
"id": "node_check_broker",
"type": "action",
"title": "Check Broker Connection",
"instruction": "Verify the VDA can communicate with the Delivery Controller on port 80/443",
"commands": [
"Test-NetConnection -ComputerName DDC-HOSTNAME -Port 80",
"Test-NetConnection -ComputerName DDC-HOSTNAME -Port 443"
],
"documentation_links": [
{
"title": "VDA to DDC Communication Ports",
"url": "https://docs.citrix.com/..."
}
],
"automation_available": false,
"next": "node_3"
},
"node_start_service": {
"id": "node_start_service",
"type": "action",
"title": "Start Citrix VDA Service",
"instruction": "Start the Citrix Virtual Desktop Agent service and check for errors",
"commands": [
"Start-Service -Name 'BrokerAgent'",
"Get-Service -Name 'BrokerAgent' | Select-Object Status"
],
"automation_available": true,
"automation": {
"type": "powershell",
"script_id": "start-citrix-vda-service",
"description": "Starts Citrix VDA service with error handling",
"requires_elevation": true,
"parameters": []
},
"next": "node_verify_registration"
},
"node_verify_registration": {
"id": "node_verify_registration",
"type": "decision",
"question": "Is the VDA now showing as registered in Citrix Studio?",
"help_text": "Open Citrix Studio > Machine Catalogs > Check VDA status",
"decision_type": "yes_no",
"yes": "node_resolved",
"no": "node_check_event_viewer"
},
"node_resolved": {
"id": "node_resolved",
"type": "resolution",
"title": "Issue Resolved",
"summary": "VDA successfully registered with Delivery Controller",
"resolution_notes": "Document the specific action that resolved the issue in the notes above."
},
"node_network_issue": {
"id": "node_network_issue",
"type": "branch",
"title": "Network Connectivity Issue Detected",
"description": "Unable to ping VDA from DDC - this is a network/firewall issue",
"suggested_next_tree": "network-connectivity-troubleshooting",
"manual_steps": [
"Check if VDA is powered on",
"Verify network cable is connected",
"Check firewall rules between DDC and VDA",
"Verify DNS resolution for VDA hostname"
]
}
}
}
```
### Session Data Structure
```json
{
"session_id": "abc-123",
"tree_id": "citrix-vda-not-registering",
"tree_snapshot": { /* full tree at time of use */ },
"user_id": "user-456",
"started_at": "2026-01-22T14:30:00Z",
"completed_at": "2026-01-22T14:45:00Z",
"ticket_number": "INC-12345",
"client_name": "City of Warner Robins",
"path_taken": [
"node_1",
"node_2",
"node_start_service",
"node_verify_registration",
"node_resolved"
],
"decisions": [
{
"node_id": "node_1",
"question": "Can you ping the VDA from the Delivery Controller?",
"answer": "yes",
"notes": "Ping successful, 2ms response time, no packet loss",
"timestamp": "2026-01-22T14:31:00Z",
"attachments": []
},
{
"node_id": "node_2",
"question": "What is the status of the Citrix Virtual Desktop Agent service?",
"answer": "stopped",
"notes": "Service was stopped. Checking dependencies - NetLogon service also stopped.",
"timestamp": "2026-01-22T14:33:00Z",
"attachments": ["attachment-id-789"]
},
{
"node_id": "node_start_service",
"action_performed": "Started Citrix VDA service",
"notes": "Started NetLogon first, then BrokerAgent. Both services now running.",
"automation_used": false,
"timestamp": "2026-01-22T14:40:00Z",
"attachments": []
},
{
"node_id": "node_verify_registration",
"question": "Is the VDA now showing as registered in Citrix Studio?",
"answer": "yes",
"notes": "VDA shows as 'Registered' in Studio. User able to launch session successfully.",
"timestamp": "2026-01-22T14:44:00Z",
"attachments": ["screenshot-registration.png"]
}
]
}
```
## API Endpoints
### Authentication
```
POST /api/auth/register - Register new user
POST /api/auth/login - Login
POST /api/auth/logout - Logout
GET /api/auth/me - Get current user
POST /api/auth/refresh - Refresh JWT token
```
### Trees
```
GET /api/trees - List all trees (with filters)
GET /api/trees/:id - Get specific tree
POST /api/trees - Create new tree (admin/engineer only)
PUT /api/trees/:id - Update tree (admin/engineer only)
DELETE /api/trees/:id - Soft delete tree (admin only)
GET /api/trees/categories - List all categories
GET /api/trees/search - Full-text search trees
```
### Sessions
```
GET /api/sessions - List user's sessions
GET /api/sessions/:id - Get specific session
POST /api/sessions - Start new troubleshooting session
PUT /api/sessions/:id - Update session (add decisions/notes)
POST /api/sessions/:id/complete - Mark session as complete
POST /api/sessions/:id/export - Export session to formatted notes
```
### Attachments
```
POST /api/sessions/:id/attachments - Upload attachment
GET /api/sessions/:id/attachments - List attachments
GET /api/attachments/:id - Get attachment
DELETE /api/attachments/:id - Delete attachment
```
### Teams (Phase 2)
```
GET /api/teams - List teams
POST /api/teams - Create team (admin only)
GET /api/teams/:id/members - List team members
POST /api/teams/:id/members - Add team member
DELETE /api/teams/:id/members/:user_id - Remove team member
```
### Analytics (Phase 3)
```
GET /api/analytics/trees/:id/usage - Tree usage statistics
GET /api/analytics/trees/:id/paths - Common paths taken
GET /api/analytics/team/performance - Team troubleshooting metrics
GET /api/analytics/user/history - User's troubleshooting history
```
### Automation (Phase 4)
```
GET /api/automation/scripts - List available automation scripts
POST /api/automation/execute - Execute automation script
GET /api/automation/history - Automation execution history
```
## Security Considerations
### Authentication & Authorization
- JWT tokens with short expiry (15 min access, 7 day refresh)
- Role-based access control (RBAC)
- Password requirements: min 10 chars, complexity
- Rate limiting on auth endpoints
- Account lockout after failed attempts
### Data Protection
- All passwords hashed with bcrypt (cost factor 12)
- Sensitive data encrypted at rest
- HTTPS only in production
- CORS properly configured
- SQL injection prevention (parameterized queries)
- XSS prevention (input sanitization, CSP headers)
### File Upload Security
- File type validation (whitelist only)
- File size limits (10MB per file)
- Virus scanning (ClamAV integration for Phase 3)
- Separate storage domain (prevent XSS via uploads)
- Signed URLs with expiration
### API Security
- Rate limiting (100 requests/min per user)
- Request size limits
- API versioning (/api/v1/...)
- Audit logging for sensitive operations
## Performance Considerations
### Database
- Indexes on frequently queried fields
- Connection pooling
- Query optimization (EXPLAIN ANALYZE)
- Consider read replicas for Phase 3+
### Caching Strategy
- Redis for session storage (Phase 2)
- Cache frequently accessed trees
- CDN for static assets
- Browser caching headers
### Frontend Performance
- Code splitting (lazy load routes)
- Tree data cached in IndexedDB
- Debounced search inputs
- Virtualized lists for large datasets
- Optimistic UI updates
## Monitoring & Observability
### Logging
- Structured logging (JSON format)
- Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
- Request ID tracking across services
- User action auditing
### Metrics (Phase 3)
- API response times
- Database query performance
- Error rates
- User engagement metrics
- System resource usage
### Error Tracking
- Sentry integration for error tracking
- User-friendly error messages
- Automatic error reporting with context
## Deployment Strategy
### CI/CD Pipeline
1. **Development:** Local development with hot reload
2. **Testing:** Automated tests on PR
3. **Staging:** Auto-deploy to staging environment
4. **Production:** Manual approval → deploy
### Database Migrations
- Alembic for schema migrations
- Backwards-compatible changes
- Rollback capability
- Test migrations on staging first
### Backup Strategy
- Automated daily database backups
- Point-in-time recovery capability
- File storage replication
- Backup retention: 30 days
## Future Technical Considerations
### Scalability
- Horizontal scaling (multiple app servers)
- Database sharding (by team_id)
- Microservices architecture (if needed)
- Message queue for async tasks (Celery + Redis)
### Mobile Apps
- React Native for iOS/Android
- Shared API backend
- Offline-first architecture
- Push notifications for team updates
### AI/ML Integration (Phase 5+)
- Suggest next steps based on past sessions
- Auto-categorize tickets
- Predict resolution time
- Natural language tree navigation

845
docs/archive/04-FEATURE-SPECIFICATIONS.md Normal file
View File

@@ -0,0 +1,845 @@
# Feature Specifications
## Core Features (MVP)
### 1. Tree Navigation Interface
**Description:** The primary interface where engineers work through troubleshooting decision trees in real-time.
**User Flow:**
1. User selects a tree from library
2. Optionally enters ticket number and client name
3. System displays first question/decision point
4. User makes selection and optionally adds notes
5. System progresses to next appropriate node
6. Process repeats until resolution or manual exit
7. User exports completed session
**UI Components:**
- **Question Display:** Large, clear text showing current decision point
- **Decision Options:**
- Yes/No buttons (for binary decisions)
- Multiple choice buttons (for multi-option decisions)
- Action confirmation button (for action steps)
- **Notes Field:** Expandable text area for adding context
- **Navigation:**
- Back button (undo last decision)
- Progress indicator (X of Y steps, or visual tree progress)
- Exit/Save button
- **Help Panel:** Collapsible sidebar with:
- Help text for current node
- Suggested commands/scripts
- Links to documentation
- Option to attach files
**Technical Requirements:**
- State management for current position in tree
- Undo functionality (maintain decision history)
- Auto-save progress every 30 seconds
- Handle browser refresh gracefully
- Support keyboard navigation (arrow keys, enter, esc)
**Edge Cases:**
- Network disconnection during session → Save locally, sync when reconnected
- User closes browser mid-session → Recover session on return
- Tree structure changes while session active → Use snapshot of tree
- Circular tree logic → Detect and prevent infinite loops
---
### 2. Documentation Links Integration
**Description:** Contextual documentation and resource links embedded at each decision node.
**Features:**
- **Multiple Link Types:**
- Vendor documentation (Microsoft Learn, Citrix docs, etc.)
- Internal KB articles (wiki/Confluence links)
- Video tutorials (YouTube, internal training)
- Related troubleshooting trees
- **Display:**
- Show as expandable "Resources" section
- Icon indicating link type (📄 doc, 🎥 video, 🌲 tree)
- Open in new tab/window
- Preview tooltip on hover
- **Management:**
- Add/edit links in tree editor
- Track link clicks (analytics)
- Validate URLs (check for 404s)
- Support internal and external links
**Data Structure:**
```json
"documentation_links": [
{
"title": "Citrix VDA Communication Requirements",
"url": "https://docs.citrix.com/...",
"type": "vendor_docs",
"description": "Official Citrix documentation on VDA-DDC communication"
},
{
"title": "Internal: VDA Troubleshooting Guide",
"url": "https://wiki.company.com/...",
"type": "internal_kb"
},
{
"title": "Video: VDA Registration Deep Dive",
"url": "https://youtube.com/...",
"type": "video",
"duration": "8:32"
}
]
```
**UI Considerations:**
- Don't clutter main interface - use expandable sections
- Allow quick copy of URLs
- Indicate when link was last verified
- Option to suggest new links (crowdsourcing)
---
### 3. Export Functionality
**Description:** Generate professional, formatted documentation from troubleshooting sessions.
**Export Formats:**
#### Plain Text
```
Ticket #12345 - Citrix VDA Not Registering
Troubleshooting Path: Citrix VDA Diagnostics
Technician: Michael Chihlas
Date: 2026-01-22 14:30
Client: City of Warner Robins
STEPS PERFORMED:
1. Network Connectivity Check
- Can ping VDA from Delivery Controller: YES
- Note: Response time 2ms, no packet loss
2. Service Status Verification
- Citrix Virtual Desktop Agent service status: STOPPED
3. Service Recovery
- Started Citrix VDA service
- Note: Service had stopped due to NetLogon dependency failure
4. Registration Verification
- VDA showing as registered in Studio: YES
- Note: User able to launch session successfully
RESOLUTION:
Started Citrix VDA service after resolving NetLogon dependency issue.
VDA successfully registered with Delivery Controller.
ATTACHED FILES:
- eventvwr_screenshot.png
- service_status_before.txt
TIME SPENT: 15 minutes
```
#### Markdown
```markdown
# Ticket #12345 - Citrix VDA Not Registering
**Troubleshooting Path:** Citrix VDA Diagnostics
**Technician:** Michael Chihlas
**Date:** 2026-01-22 14:30
**Client:** City of Warner Robins
## Steps Performed
### 1. Network Connectivity Check
✓ Can ping VDA from Delivery Controller: **YES**
> Response time 2ms, no packet loss
### 2. Service Status Verification
✗ Citrix Virtual Desktop Agent service status: **STOPPED**
### 3. Service Recovery
✓ Started Citrix VDA service
> Service had stopped due to NetLogon dependency failure
### 4. Registration Verification
✓ VDA showing as registered in Studio: **YES**
> User able to launch session successfully
## Resolution
Started Citrix VDA service after resolving NetLogon dependency issue. VDA successfully registered with Delivery Controller.
## Attached Files
- [eventvwr_screenshot.png](link)
- [service_status_before.txt](link)
---
**Time Spent:** 15 minutes
```
#### HTML
- Styled version of markdown
- Embeds images inline
- Collapsible sections
- Print-friendly CSS
- Copy button for easy paste into web forms
**Customization Options:**
- Include/exclude sections (steps, resolution, attachments, time)
- Custom header/footer
- Branding/logo
- Date/time format
- Technician name format
- Template selection (different formats for different ticket systems)
**Technical Implementation:**
- Backend template engine (Jinja2)
- Frontend preview before export
- Copy to clipboard functionality
- Download as file
- Send via email (Phase 3)
---
### 4. Tree Editor
**Description:** Visual interface for creating and editing decision trees.
**Editing Modes:**
- **Visual Mode:** Drag-and-drop node editor (like flowchart)
- **Form Mode:** Fill-in-the-blanks forms for each node
- **JSON Mode:** Direct JSON editing (for advanced users)
**Node Types:**
1. **Decision Node:** Question with multiple possible answers
2. **Action Node:** Instruction to perform a task
3. **Resolution Node:** Terminal node indicating issue resolved
4. **Branch Node:** Link to another tree or manual escalation
**Node Configuration:**
- **Common Fields:**
- Node ID (auto-generated, editable)
- Node type
- Title/Question text
- Help text (optional)
- Documentation links (optional)
- Allow notes (toggle)
- Allow attachments (toggle)
- Allow custom branch (toggle)
- **Decision Node Specific:**
- Decision type (yes/no, multiple choice, numeric range)
- Options and next node for each
- **Action Node Specific:**
- Action instructions
- Commands/scripts to run
- Expected outcome
- Automation available (toggle)
- Automation configuration
- Next node
- **Resolution Node Specific:**
- Resolution summary template
- Success criteria
- Follow-up recommendations
**Tree Metadata:**
- Tree name
- Description
- Category/tags
- Estimated time to complete
- Difficulty level
- Author
- Version
- Creation/update dates
**Validation:**
- No orphaned nodes (every node reachable from start)
- No circular references (detect loops)
- Every decision has valid next nodes
- Terminal nodes exist
- Required fields filled
**UI Features:**
- Auto-save draft
- Preview mode (test the tree)
- Duplicate tree (create variations)
- Import/export tree JSON
- Publish (make active) vs. Draft
- Version history (Phase 3)
---
### 5.5 User Preferences (MVP)
**Description:** Basic user settings to personalize the application experience, stored locally for MVP with optional server sync in later phases.
**MVP Settings:**
| Setting | Options | Default | Storage |
|---------|---------|---------|--------|
| Theme | Light / Dark / System | System | localStorage |
| Default Export Format | Markdown / Text / HTML | Markdown | localStorage |
**UI Components:**
- **Settings Access:** Gear icon in user menu dropdown
- **Settings Modal:** Simple modal with toggle/dropdown for each setting
- **Theme Toggle:** Can also be quick-access icon in header
**Theme Implementation:**
```
Light Mode:
- Background: White/light gray
- Text: Dark gray/black
- Accents: Brand colors
Dark Mode:
- Background: Dark gray (#1a1a2e or similar)
- Text: Light gray/white
- Accents: Adjusted brand colors for dark backgrounds
System:
- Follows OS preference via prefers-color-scheme media query
- Updates automatically if OS setting changes
```
**Technical Requirements:**
- Persist to localStorage immediately on change
- Apply theme without page reload (CSS variables)
- Respect system preference on first visit
- Export format preference used as default in export dialog
**Future Enhancements (Phase 2+):**
- Sync preferences to user account (database)
- More settings: auto-save interval, keyboard shortcuts, notification preferences
- Per-tree preferences (remember last used export format per tree)
---
### 5. Attachment Support
**Description:** Upload and attach files (screenshots, logs, command outputs) to specific decision nodes during troubleshooting.
**Supported File Types:**
- Images: PNG, JPG, GIF, WebP
- Documents: TXT, LOG, CSV, JSON, XML
- Screenshots: Direct paste from clipboard (Ctrl+V)
- Archives: ZIP (for bundled logs)
**File Size Limits:**
- Individual file: 10 MB
- Per session: 50 MB
- Total per user: 500 MB (soft limit, alert before reaching)
**Upload Methods:**
1. **File Picker:** Click to browse and select
2. **Drag & Drop:** Drag files onto upload area
3. **Paste:** Ctrl+V to paste screenshot from clipboard
4. **Command Output:** Copy-paste terminal output, save as .txt
**Features:**
- **Preview:** Thumbnail for images, icon for others
- **Annotation:** Add caption/description to each file
- **Organize:** Files associated with specific decision node
- **Download:** Download individual files or all as ZIP
- **Delete:** Remove unwanted attachments
- **Reference in Notes:** Auto-reference in export ("See attached screenshot")
**Storage:**
- S3-compatible object storage
- Organized by session_id/node_id/filename
- Pre-signed URLs for secure access
- Automatic cleanup of old sessions (retention policy)
**Export Integration:**
- List attached files in export
- Include inline images in HTML/PDF exports
- Provide download links in text/markdown exports
- Option to bundle as ZIP with export
**Technical Considerations:**
- Virus scanning (Phase 3)
- Content-Type validation
- Generate thumbnails for images
- Compress images to reduce storage
- CDN for faster delivery
---
## Advanced Features (Phase 3+)
### 6. Automation Integration
**Description:** Execute PowerShell scripts or commands directly from action nodes, capturing output and integrating into troubleshooting flow.
**Architecture:**
```
Frontend → Backend API → Automation Worker → PowerShell/Script → Return Output
```
**Safety Mechanisms:**
- **Execution Sandbox:** Isolated environment, limited permissions
- **Timeout:** Max execution time (5 minutes default)
- **Resource Limits:** CPU, memory, network constraints
- **Approval Required:** Sensitive scripts need admin approval
- **Audit Log:** Every execution logged with user, timestamp, parameters, output
**Script Types:**
1. **Read-Only:** Get information (Get-Service, Test-Connection)
2. **Safe Actions:** Restart services, clear caches
3. **Configuration Changes:** Modify settings (require extra confirmation)
**User Experience:**
- **Option at Action Node:** "Run Automation" vs. "Manual" buttons
- **Parameter Input:** If script needs parameters (hostname, username)
- **Progress Indicator:** Show script is running
- **Output Display:** Show script output in real-time or after completion
- **Error Handling:** Clear error messages, suggest manual steps
- **Capture Output:** Automatically save output as attachment
**Script Management:**
- **Script Library:** Centralized repository of approved scripts
- **Versioning:** Track script versions
- **Testing:** Test mode before production use
- **Permissions:** Control who can run which scripts
- **Documentation:** Each script has description, parameters, example usage
**Integration with ChihlasChecker:**
- Import existing PowerShell scripts
- Wrap scripts with parameter handling
- Standardize output format
- Error code mapping
**Example Script Configuration:**
```json
{
"script_id": "restart-citrix-vda-service",
"name": "Restart Citrix VDA Service",
"description": "Restarts the Citrix Virtual Desktop Agent service and its dependencies",
"type": "powershell",
"requires_elevation": true,
"timeout_seconds": 300,
"parameters": [
{
"name": "ComputerName",
"type": "string",
"required": true,
"description": "VDA hostname or IP address",
"validation": "^[a-zA-Z0-9.-]+$"
}
],
"script": "path/to/script.ps1",
"risk_level": "medium",
"approval_required": false
}
```
---
### 7. Offline Mode
**Description:** Continue using the application without internet connectivity, with automatic sync when connection restored.
**Offline Capabilities:**
- Navigate cached trees
- Add notes and make decisions
- Queue file attachments (upload when online)
- View past sessions (cached)
**What Requires Online:**
- Creating new trees
- Sharing with team
- Accessing uncached trees
- Running automation
- Real-time collaboration
**Technical Implementation:**
- **Service Worker:** Intercept network requests, serve from cache
- **IndexedDB:** Store trees, sessions, user data locally
- **Sync Queue:** Track changes made offline, sync when online
- **Conflict Resolution:** Handle conflicts if tree was updated while offline
**User Experience:**
- **Status Indicator:** Clear online/offline badge
- **Sync Status:** "Syncing..." indicator when uploading changes
- **Cache Management:** Settings to control what's cached
- **Manual Sync:** Button to force sync attempt
**Data Synchronization:**
1. User goes offline mid-session
2. Continues making decisions, adding notes (stored locally)
3. Attempts to attach file (queued for upload)
4. User regains connection
5. System detects online status
6. Uploads queued attachments
7. Syncs session data to server
8. Resolves any conflicts
9. Updates local cache with server changes
**Conflict Resolution:**
- Last-write-wins for session data (sessions are user-specific)
- Alert user if tree structure changed significantly
- Option to review changes before syncing
---
### 8. Client Context System
**Description:** Store and auto-populate client-specific information to speed up troubleshooting and reduce repetitive data entry.
**Stored Context:**
- **Infrastructure Details:**
- Server names (DC names, Citrix DDC, file servers)
- IP addresses and subnets
- Domain names
- VPN configurations
- **Common Issues:**
- Known recurring problems
- Specific quirks of client environment
- **Contact Information:**
- Primary contacts
- Escalation paths
- **Documentation Links:**
- Client-specific network diagrams
- Password vault links
- Configuration management links
**Features:**
- **Client Selection:** Dropdown or search to select client at session start
- **Auto-Population:** When client selected, pre-fill known values in tree
- **Context Cards:** Display relevant client info in sidebar during troubleshooting
- **Quick Edit:** Update client context without leaving session
- **Privacy:** Sensitive data encrypted, access controlled
**Example Usage:**
1. User starts session for "City of Warner Robins"
2. System loads Warner Robins context
3. When tree asks "What is the primary domain controller?", it pre-fills "WR-DC01"
4. User can accept or override
5. Saves time and reduces errors
**Data Structure:**
```json
{
"client_id": "warner-robins-city",
"client_name": "City of Warner Robins",
"context": {
"domain_controllers": ["WR-DC01.wrga.local", "WR-DC02.wrga.local"],
"citrix_ddc": ["WR-CTX01.wrga.local"],
"file_servers": ["WR-FS01.wrga.local"],
"subnets": ["10.20.0.0/16"],
"vpn_gateway": "vpn.wrga.gov",
"primary_contact": "John Smith - IT Director",
"escalation": "jane.doe@wrga.gov",
"notes": "Always check VPN tunnel to courthouse first - frequently drops"
}
}
```
---
### 9. "Send to Engineer" Feature
**Description:** Generate a simplified, read-only view or checklist from a decision tree that can be shared with onsite engineers or junior staff.
**Use Cases:**
- Remote engineer creates troubleshooting plan
- Shares link with onsite tech
- Onsite tech follows steps, reports results
- Remote engineer updates plan if needed
**Features:**
- **Simplified View:** Streamlined UI, just the steps
- **Checklist Mode:** Check off completed steps
- **Print-Friendly:** Clean layout for printing
- **Share Link:** Generate unique URL, no login required (optional)
- **QR Code:** For easy mobile access
- **Expiration:** Links expire after X hours/days
- **Password Protection:** Optional password for sensitive clients
**Generated Content:**
```
Warner Robins - VDA Registration Issue
Generated by: Michael Chihlas
Date: 2026-01-22
[ ] Step 1: Check network connectivity
From DDC, run: ping WR-VDA05
Expected: Replies with <5ms latency
[ ] Step 2: Verify VDA service status
Run: Get-Service BrokerAgent
Expected: Status = Running
[ ] Step 3: If service stopped, start it
Run: Start-Service BrokerAgent
Wait 30 seconds
[ ] Step 4: Verify registration
Open Citrix Studio
Check Machine Catalogs
Expected: WR-VDA05 shows "Registered"
Notes/Results:
[Space for onsite tech to write notes]
Contact remote engineer if issues: michael@msp.com
```
**Technical Implementation:**
- Generate static HTML page from tree
- Store in temporary location (S3)
- Track access (analytics)
- Auto-delete after expiration
- Optional: Collect results back (if onsite tech submits form)
---
### 10. Personal Tree Branching (Phase 2.5)
**Description:** Allow users to insert custom steps during an active troubleshooting session without modifying the original tree, then optionally save their modified version as a personal tree.
**User Flow:**
1. User navigates an official tree
2. At any decision point, user clicks "+ Add Custom Step"
3. User creates step manually OR selects from Step Library
4. Custom step is inserted into their session only (original tree unchanged)
5. Session continues with custom step included
6. Export includes all custom steps with clear marking
7. After session completion, user is prompted to save as personal tree (optional)
**UI Components:**
- **Add Custom Step Button:** Appears at each decision node
- **Step Creation Modal:**
- Tab 1: "Type My Own" - free-form step creation
- Tab 2: "Browse Library" - searchable step repository
- **Custom Step Indicator:** Visual badge showing step is user-added (not from original tree)
- **Save as Tree Prompt:** Post-session dialog offering to save modifications
**Step Types:**
1. **Decision:** Yes/No or multiple choice question
2. **Action:** Task to perform with optional commands/scripts
3. **Resolution:** Terminal node indicating issue resolved
**Technical Requirements:**
- Custom steps stored separately from original tree structure
- Session tracks insertion points (after which node ID)
- Export template renders custom steps with visual distinction
- Tree fork creates deep copy with user as owner
- Forked trees maintain reference to original (for analytics/updates)
**Edge Cases:**
- Original tree updated after fork → Notify user, offer to view changes
- User deletes custom step mid-session → Remove from session, continue normally
- Circular reference from custom step → Validate and prevent before insertion
- Custom step at terminal node → Allow, becomes new branch point
---
### 11. Step Library (Phase 2.5)
**Description:** A repository of reusable troubleshooting steps that users can pull into any session, organized by visibility, categories, tags, and user ratings.
**Library Hierarchy:**
- **My Steps:** Private to individual user
- **Team Steps:** Visible to all team members
- **Admin Curated:** Organization-wide, managed by administrators
- **Community/Public:** User-contributed, rated by users, visible to all
**Features:**
- **Search & Filter:**
- Full-text search across titles, descriptions, commands
- Filter by step type (decision, action, resolution)
- Filter by category (admin-managed)
- Filter by tags (user-defined)
- Filter by visibility level
- Filter by minimum rating (e.g., 4+ stars)
- Sort by: recent, popular, highest rated, most used
- **Step Preview:**
- View full step details before inserting
- See usage count and rating breakdown
- View author, creation date, and last updated
- See category and tags
- **Step Management:**
- Create new steps (saved to "My Steps" by default)
- Assign category and add tags during creation
- Edit and delete own steps
- Promote to Team visibility (if permitted)
- Submit to Community (requires admin approval)
#### Categories (Admin-Managed)
Categories provide structured organization for steps. Admins define and manage categories.
**Default Categories:**
| Category | Description |
|----------|-------------|
| Citrix / VDI | Virtual desktop, XenApp, XenDesktop, VDA issues |
| Active Directory | AD, LDAP, Group Policy, authentication |
| Microsoft 365 | Exchange Online, Teams, SharePoint, OneDrive |
| Networking | DNS, DHCP, VPN, firewall, connectivity |
| File Services | File shares, permissions, DFS, storage |
| Printing | Print servers, drivers, spooler issues |
| Backup & Recovery | Backup software, disaster recovery, restore |
| Security | Antivirus, permissions, security incidents |
| Hardware | Servers, workstations, peripherals |
| Other | Miscellaneous steps |
#### Tags (User-Defined)
Tags provide flexible, user-driven organization:
- Created by any user when adding/editing a step
- Lowercase, alphanumeric with hyphens (e.g., `vda-registration`, `powershell`)
- Auto-suggest existing tags while typing
- Popular tags shown as quick-filters
- Recommended: 3-5 tags per step
#### User Ratings & Reviews
Public and team steps can be rated by users to surface the most helpful content.
**Rating System:**
- **Star Rating:** 1-5 stars (required when rating)
- **Helpful Vote:** Quick "Was this helpful?" Yes/No after using a step
- **Written Review:** Optional text feedback (max 500 chars)
- **One rating per user per step** (can update later)
**Rating Rules:**
- Only users who have actually used the step can rate it ("Verified Use" badge)
- Step author cannot rate their own step
- Ratings update the step's average in real-time
- Steps with <5 ratings show "Not enough ratings" instead of average
- Admin can remove abusive reviews
**Admin Controls:**
- Approve/reject community step submissions
- Curate "Admin Curated" collection
- Manage categories (create, rename, archive)
- Remove inappropriate content/reviews
- Set default visibility for new steps
---
### 12. Personal Tree Management (Phase 2.5)
**Description:** Users can save, organize, and share their customized tree versions.
**Features:**
- **My Trees Dashboard:**
- List of user's forked/custom trees
- Reference to original tree (if forked)
- Last used date and usage count
- Quick actions: start session, edit, share, delete
- **Tree Forking:**
- Fork from any tree user has access to
- Fork from another user's shared tree (fork of fork)
- Maintain lineage tracking for analytics
- **Sharing Options:**
- 🔒 Private - Only creator can access
- 🔗 Link sharing - Anyone with link, no login required
- 👥 Team - All team members can use
- 🌍 Public - Submitted to community library
- **Version Awareness:**
- Notification when original tree is updated
- Option to view changes (basic diff)
- Manual merge in future phase
**Forking Behavior:**
- Deep copy of entire tree structure
- User becomes owner of the copy
- Original tree reference preserved
- Changes to original don't affect fork (until user chooses to merge)
- Fork count tracked on original tree (analytics)
**Sharing Permissions:**
- Owner can change visibility at any time
- "Allow forking" toggle controls whether others can fork
- "Show author" toggle controls name visibility
- Revoking link sharing invalidates existing links
---
## Feature Priority Matrix
| Feature | MVP | Phase 2 | Phase 2.5 | Phase 3 | Phase 4 |
|---------|-----|---------|-----------|---------|---------|
| Tree Navigation | ✓ | | | | |
| Basic Export | ✓ | | | | |
| User Auth | ✓ | | | | |
| **User Preferences** | **✓** | | | | |
| 5 Starter Trees | ✓ | | | | |
| Team Management | | ✓ | | | |
| Tree Editor | | ✓ | | | |
| Mobile Responsive | | ✓ | | | |
| Basic Custom Branches | | ✓ | | | |
| **Step Library** | | | **✓** | | |
| **Categories & Tags** | | | **✓** | | |
| **Ratings & Reviews** | | | **✓** | | |
| **Personal Tree Branching** | | | **✓** | | |
| **Tree Forking & Sharing** | | | **✓** | | |
| File Attachments | | | | ✓ | |
| Offline Mode | | | | ✓ | |
| Advanced Export (PDF) | | | | ✓ | |
| Client Context | | | | ✓ | |
| Send to Engineer | | | | ✓ | |
| Analytics Dashboard | | | | ✓ | |
| Documentation Links | ✓ | Enhanced | | | |
| API | | | | | ✓ |
| Automation Integration | | | | | ✓ |
| PSA Integrations | | | | | ✓ |
| Marketplace | | | | | Later |
---
## User Stories
### Michael (Senior Engineer)
- "I need to quickly document my troubleshooting steps for a ticket"
- "I want to reuse proven troubleshooting paths instead of reinventing"
- "I need to attach screenshots to show what I found"
- "I want to create custom trees for our specific environment"
- "I need this to work when I'm on-site with poor connectivity"
### Junior Engineer
- "I need guidance on how to troubleshoot issues I'm not familiar with"
- "I want to know what commands to run and what results to expect"
- "I need links to documentation when I get stuck"
- "I want to learn from what senior engineers do"
### Onsite Technician
- "I need simple, step-by-step instructions I can follow"
- "I want a checklist I can print and bring to the server room"
- "I need to report back results to the remote engineer"
### MSP Manager
- "I need to see what my team is working on"
- "I want to ensure we're following consistent procedures"
- "I need metrics on troubleshooting time and success rates"
- "I want to identify training gaps based on common issues"
### Phase 2.5 User Story Additions
**Michael (Senior Engineer):**
- "I want to add a client-specific step without changing the official tree"
- "I want to save my modified tree so I can reuse it for this client"
- "I want to share a troubleshooting approach with a colleague via link"
- "I want to build a library of steps I commonly use across different trees"
- "I want to rate steps that helped me so others can find them"
**Junior Engineer:**
- "I want to see what custom steps senior engineers have created"
- "I want to use proven steps from the team library instead of creating my own"
- "I want to fork a senior engineer's tree and learn from their approach"
- "I want to filter steps by rating to find the best ones"
- "I want to see reviews from others who used a step"
**MSP Manager:**
- "I want to curate a set of approved steps for my team"
- "I want to see which custom steps are being used most"
- "I want to approve steps before they're shared publicly"
- "I want to manage categories to keep the step library organized"
- "I want to moderate reviews for inappropriate content"

342
docs/archive/05-QUESTIONS-AND-ACTION-ITEMS.md Normal file
View File

@@ -0,0 +1,342 @@
# Questions & Action Items
## Questions for Michael
### Timeline & Resources
**1. Timeline Pressure**
- Do you need something usable in 2 weeks, or can we take 4-6 weeks to build something more polished?
- What's driving the timeline? (Personal productivity? Team need? Demonstration?)
> 50% personal and 50% I see a need in the market
**2. Your Involvement**
- Can you commit ~2 hours per week for feedback/testing during development?
- Or do you need this to be more hands-off until it's ready?
- Preferred communication: Slack/email/scheduled calls?
> I can commit likely more than 2 hours a week. I'm willing to spend most of my evenings working on this if needed.
**3. Hosting Budget**
- Start with free tier on Render/Railway (with limitations)?
- Willing to spend $10-20/month for better performance/storage?
- Company paying or personal expense?
> I'm definitely willing to spend $20/month
**4. Team Size**
- How many engineers would be using this in the first 3 months?
- 1-3 people? (affects database/hosting decisions)
- 5-10 people?
- 10+ people?
- Are they all at the same skill level as you, or mix of junior/senior?
> In the first 3 months, I could see maybe 3 people other than myself at maximum. Depending upon how quickly a working model is out, it could potentially be more based upon adoption rate and how easy it is to build out the trees.
**5. Branding**
- Personal project with your name on it? ("ChihlasTree" or similar)
- MSP company tool? (Company branding)
- Intentionally generic for broader appeal? (TroubleTree, DiagPath, etc.)
> This started as a personal project idea, however, making money from this idea is the goal. So generic may not be bad.
---
## Action Items for Michael
### High Priority (Before Development Starts)
**1. Document Your Top 5 Troubleshooting Scenarios**
For each scenario, I need:
- Issue name/category
- First thing you check
- What the possible outcomes are
- What you do for each outcome
- How you know when you've solved it
- Common pitfalls or edge cases
**Example Template:**
```
Issue: FSLogix Profile Not Loading
Category: Citrix/Virtual Desktop
Step 1: Can user log into server?
├─ YES → Step 2: Check FSLogix service
└─ NO → Different tree (AD/Licensing issue)
Step 2: Is FSLogix service running?
├─ RUNNING → Step 3: Check frxtray.exe in task manager
├─ STOPPED → Step 4: Start service, check event log
└─ STUCK → Step 5: Kill and restart, check file locks
Step 3: Does user have profile VHD in share?
├─ YES → Step 6: Check permissions on VHD
└─ NO → Step 7: Check FSLogix registry settings
... (continue until resolution)
Common Pitfalls:
- VHD file locked by another server
- Profile path in registry has typo
- Antivirus blocking VHD access
Resolution Indicators:
- User can log in successfully
- Profile loads within 30 seconds
- No FSLogix errors in Event Viewer
```
> For the above section, please see a document called TS-EXAMPLES.md in this project folder.
**Your Top 5 to Document:**
1. [ ] Citrix VDA Not Registering
2. [ ] FSLogix Profile Issues
3. [ ] Active Directory Replication Failure
4. [ ] SonicWall VPN Tunnel Down
5. [ ] User Unable to Access File Share (permissions vs. connectivity)
**2. Export Format Sample**
Create a sample ticket note from a recent ticket that shows:
- How you currently document troubleshooting steps
> Typically this is done with bullet points with short concise sentences. At times there will be screenshots and if I think a specific command that is run is important, I will put that in too.
- The level of detail your ticketing system needs
> As detailed as possible without being bloated
- Any specific formatting requirements
> Nothing specific, I'm open to what works best
- Whether you include timestamps, commands run, etc.
> Timestamps are sometimes included, commands are also included unless it becomes an entire script in which case that is added as an attachment.
This will help me design exports that match your existing workflow.
**3. Team Feedback (Optional but Valuable)**
If possible, ask 1-2 colleagues:
- "If there was a tool that guided you through troubleshooting and automatically wrote your ticket notes, what would make it actually useful vs. just another tool to learn?"
- What's their biggest pain point in documenting work?
- Do they follow consistent troubleshooting paths, or is it different every time?
---
### Medium Priority (Can Be Done During Development)
**4. Documentation Link Collection**
Start collecting useful documentation links you reference frequently:
- Microsoft Learn articles
- Citrix documentation
- Internal wiki pages
- YouTube tutorials
- Blog posts that have saved you
We'll integrate these into the trees as we build them.
**5. Client Context Template**
For 1-2 of your main clients (like City of Warner Robins), document:
- Domain controller names
- Key server hostnames
- Network information (subnets, VPN gateway)
- Common issues specific to that client
- Primary contacts
This will help us design the client context feature properly.
**6. Script Inventory**
List your PowerShell scripts/tools that you'd eventually want to integrate:
- ChihlasChecker scripts
- Service restart scripts
- Common diagnostic commands
- Any automation you do repeatedly
We won't integrate these in MVP, but good to know what exists for Phase 4.
---
### Low Priority (Nice to Have)
**7. Naming Ideas**
Brainstorm some names for the tool:
- Should it have "Chihlas" in the name? (personal branding)
- Should it sound MSP-specific or generic?
- Should it be playful or professional?
Some ideas to react to:
- TroubleTree
- DecisionPath
- FlowDoc
- DiagnosticFlow
- PathFinder
- TicketFlow
- ChihlasTree
- MSP Navigator
**8. Long-term Vision**
Think about:
- Would you want to eventually sell this to other MSPs?
- Keep it as internal tool for your company?
- Open-source it to build reputation?
- Use it as consulting/training material?
> I would like to profit off this to other MSPs, internal IT teams, and I can see applications for this in many other markets outside of IT. This could end up being used in call centers, or telemarketing even. This could also be used on a consulting basis for other MSPs and private clients.
This affects architectural decisions (multi-tenancy, white-labeling, etc.)
---
## Decision Log
*This section will be updated as we make key decisions*
| Date | Decision | Rationale |
|------|----------|-----------|
| TBD | Tech stack: React + FastAPI + PostgreSQL | Michael learning Python, modern stack, flexible |
| TBD | Hosting: [To be decided] | Based on budget and team size |
| TBD | Name: [To be decided] | Based on branding goals |
| TBD | Timeline: [To be decided] | Based on urgency and availability |
---
## Next Steps
### Immediate (This Week)
1. [ ] Michael answers the 5 key questions above
2. [ ] Michael documents 2-3 troubleshooting scenarios in detail
3. [ ] Michael provides sample export format
4. [ ] Decision on timeline and hosting budget
5. [ ] Confirm tech stack choices
### Week 1 (When Development Starts)
1. [ ] Set up development environment
2. [ ] Create project repository (GitHub)
3. [ ] Initial database schema
4. [ ] Basic authentication working
5. [ ] First tree manually created in database
### Week 2
1. [ ] Basic tree navigation UI functional
2. [ ] Michael tests with real scenario
3. [ ] Iterate based on feedback
4. [ ] Add export functionality
5. [ ] Create 2-3 more trees
### Week 3
1. [ ] Polish UI based on usage
2. [ ] Fix critical bugs
3. [ ] Deploy to production (staging environment)
4. [ ] Michael uses on real tickets
5. [ ] Collect usage data and feedback
---
## Open Questions & Parking Lot
*Questions that arise during development but don't need immediate answers*
### Technical Questions
- Should we support tree branching (go to Tree B from Tree A)?
- How deep should tree history go? (unlimited or limited?)
- Should users be able to fork/duplicate trees?
- Real-time collaboration on trees? (Google Docs style)
### Product Questions
- Gamification? (badges for completing troubleshooting, streaks?)
- AI suggestions based on past sessions?
- Integration with time tracking tools?
- Mobile app vs. responsive web?
### Business Questions
- Pricing model if commercialized?
- Target market research needed?
- Patent/trademark considerations?
- Partnership opportunities with PSA vendors?
---
## Meeting Notes Template
*For regular check-ins during development*
### Meeting [Date]
**Attendees:**
**Agenda:**
1. Review progress since last meeting
2. Demo new features
3. Gather feedback
4. Discuss blockers
5. Plan next sprint
**Progress:**
- [ ] Item 1
- [ ] Item 2
**Feedback:**
-
**Blockers:**
-
**Next Sprint Goals:**
1.
2.
3.
**Action Items:**
- [ ] Michael: [task]
- [ ] Development: [task]
**Next Meeting:** [Date/Time]
---
## Resources & References
### Documentation
- React: https://react.dev/
- FastAPI: https://fastapi.tiangolo.com/
- PostgreSQL: https://www.postgresql.org/docs/
- Tailwind CSS: https://tailwindcss.com/docs
### Design Inspiration
- Linear (project management): https://linear.app/
- Notion (documentation): https://notion.so/
- Flowchart tools: Lucidchart, Miro, Whimsical
### Similar Tools (Competitors/Inspiration)
- ServiceNow Knowledge Base
- IT Glue
- Atlassian Confluence Decision Trees
- Custom runbook platforms
### Learning Resources
- "Don't Make Me Think" (UX book)
- "The Mom Test" (customer development)
- MSP Reddit communities
- Spiceworks forums
---
## Contact & Communication
**Primary Communication Channel:** [To be decided]
- Slack?
- Email?
- Discord?
- GitHub Issues?
**Preferred Meeting Schedule:** [To be decided]
- Weekly check-ins?
- Bi-weekly reviews?
- Ad-hoc as needed?
**Response Time Expectations:**
- Urgent issues (blocking development): [X hours]
- Feature feedback: [X days]
- General questions: [X days]
---
## Version History
| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 0.1 | 2026-01-22 | Initial draft | Claude |
| | | | |

4
docs/archive/IGNORE-prompts.md Normal file
View File

@@ -0,0 +1,4 @@
Read CLAUDE-SETUP.md, CURRENT-STATE.md, and LESSONS-LEARNED.md first.
- In the Options area when creating a new action/question/solution allow it to be named to be used for the next option created.
-In the preview pane, when the solution is attached to an action or question, it's always shown under the action or question it was created/attached to first. I believe it needs to be shown under the lowest available option, or the visual needs to be changed entirely when a solution is attached to more than one option.

520
docs/archive/PROGRESS.md Normal file
View File

@@ -0,0 +1,520 @@
# Project Patherly - Development Progress
**Last Updated**: January 29, 2026
**Current Phase**: Phase 2 Frontend - COMPLETE & TESTED
---
## Project Overview
Building a troubleshooting decision tree web application for MSP engineers. The app allows creating, managing, and navigating through decision trees for common IT support scenarios.
**Tech Stack**:
- Backend: Python FastAPI + SQLAlchemy 2.0 (async) + PostgreSQL
- Frontend: React 18 + Vite + TypeScript + Tailwind CSS + Zustand
- Hosting: Render (dev) / Railway Pro (production)
---
# Patherly Development Progress
> 📚 **Reference**: See [CLAUDE-SETUP.md](./CLAUDE-SETUP.md) for available
> development tools and usage guidelines
## Completed Work
### Phase 1a: Backend API (COMPLETE)
All backend components have been created following `02-TECHNICAL-ARCHITECTURE.md` exactly.
#### Project Structure Created
```
backend/
├── alembic/ # Database migrations
│ ├── versions/
│ │ └── 001_initial_schema.py
│ ├── env.py
│ └── script.py.mako
├── app/
│ ├── api/
│ │ ├── endpoints/
│ │ │ ├── auth.py # Authentication (register, login, refresh, logout)
│ │ │ ├── trees.py # Trees CRUD + search
│ │ │ └── sessions.py # Sessions + export (md, txt, html)
│ │ ├── deps.py # Auth dependencies (get_current_user, role checks)
│ │ └── router.py # Main API router
│ ├── core/
│ │ ├── config.py # Settings via pydantic-settings
│ │ ├── database.py # Async SQLAlchemy engine + session
│ │ └── security.py # JWT creation/validation + bcrypt
│ ├── models/
│ │ ├── user.py # User model (UUID, email, role, team_id)
│ │ ├── team.py # Team model
│ │ ├── tree.py # Tree model (JSONB tree_structure)
│ │ ├── session.py # Session model (path tracking)
│ │ └── attachment.py # Attachment model (file uploads)
│ ├── schemas/
│ │ ├── user.py # User Pydantic schemas
│ │ ├── token.py # JWT token schemas
│ │ ├── tree.py # Tree request/response schemas
│ │ └── session.py # Session schemas + export
│ └── main.py # FastAPI application entry point
├── alembic.ini
├── docker-compose.yml # PostgreSQL 16 container
├── requirements.txt
├── .env.example
└── README.md
```
#### Database Schema (5 tables)
- `users` - User accounts with roles (admin, engineer, viewer)
- `teams` - Team groupings for users
- `trees` - Decision trees with JSONB structure, versioning, categories
- `sessions` - Troubleshooting sessions with path tracking
- `attachments` - File attachments for sessions
#### API Endpoints Implemented
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/auth/register` | User registration |
| POST | `/api/v1/auth/login` | Login (form data) |
| POST | `/api/v1/auth/login/json` | Login (JSON body) |
| POST | `/api/v1/auth/refresh` | Refresh access token |
| GET | `/api/v1/auth/me` | Get current user |
| POST | `/api/v1/auth/logout` | Logout (client-side) |
| GET | `/api/v1/trees` | List trees (paginated) |
| POST | `/api/v1/trees` | Create tree |
| GET | `/api/v1/trees/categories` | Get unique categories |
| GET | `/api/v1/trees/search` | Full-text search |
| GET | `/api/v1/trees/{id}` | Get tree by ID |
| PUT | `/api/v1/trees/{id}` | Update tree |
| DELETE | `/api/v1/trees/{id}` | Soft delete tree |
| GET | `/api/v1/sessions` | List user's sessions |
| POST | `/api/v1/sessions` | Start new session |
| GET | `/api/v1/sessions/{id}` | Get session |
| PUT | `/api/v1/sessions/{id}` | Update session (add decisions) |
| POST | `/api/v1/sessions/{id}/complete` | Mark session complete |
| POST | `/api/v1/sessions/{id}/export` | Export session (md/txt/html) |
#### Key Technical Decisions
- **UUIDs**: All primary keys use PostgreSQL `gen_random_uuid()`
- **JSONB**: Tree structures and session paths stored as JSONB
- **JWT Auth**: 15-minute access tokens, 7-day refresh tokens
- **Password Hashing**: bcrypt with cost factor 12
- **Full-text Search**: PostgreSQL `to_tsvector` on tree name/description
- **Soft Deletes**: Trees use `is_active` flag (set to false on delete)
- **Async**: All database operations use async SQLAlchemy
- **Timezone-Aware DateTime**: All timestamps use `DateTime(timezone=True)` and UTC storage
---
## Recent Bug Fixes & Improvements (January 28, 2026)
### DateTime Handling Fix ✅
**Issue**: Mixing timezone-aware and timezone-naive datetime objects caused Internal Server Errors in session completion and updates.
**Resolution** (Following [FastAPI/SQLAlchemy 2026 best practices](https://medium.com/@rameshkannanyt0078/how-to-handle-timezones-properly-in-fastapi-and-database-68b1c019c1bc)):
- Updated all SQLAlchemy models to use `DateTime(timezone=True)`
- Changed all default datetime factories to `lambda: datetime.now(timezone.utc)`
- Ensures all timestamps are timezone-aware and stored in UTC
- Affected models: User, Team, Tree, Session, Attachment
### Production Logging System ✅
**Added** (Following [2026 FastAPI logging standards](https://betterstack.com/community/guides/logging/logging-with-fastapi/)):
- **Structured logging configuration** with development/production modes
- **Request correlation IDs** for distributed tracing
- **Log rotation** (10MB files, 10 backups) for long-running applications
- **Separate loggers** for application, error, and access logs
- **Request/response middleware** with timing metrics
New files:
- `backend/app/core/logging_config.py` - Main logging configuration
- `backend/app/core/middleware.py` - Request logging and error capture middleware
### Comprehensive Integration Tests ✅
**Created** full test suite with 29 integration tests (all passing):
- **Test Framework**: pytest 7.4.3 with pytest-asyncio 0.23.0
- **Test Database**: Separate PostgreSQL test database (`patherly_test`)
- **Coverage**: Auth, Trees, and Sessions endpoints
- **Fixtures**: Reusable test user, admin user, auth headers, and test tree fixtures
New test files:
- `backend/tests/conftest.py` - Test configuration and fixtures
- `backend/tests/test_auth.py` - Authentication endpoint tests (7 tests)
- `backend/tests/test_trees.py` - Tree CRUD and search tests (10 tests)
- `backend/tests/test_sessions.py` - Session workflow tests (12 tests)
- `backend/pytest.ini` - Pytest configuration with coverage
- `backend/requirements-dev.txt` - Development dependencies
**Test Coverage**:
- ✅ User registration and login flows (including role-based registration)
- ✅ JWT token generation and validation
- ✅ Tree CRUD operations (create, read, update, delete)
- ✅ Full-text tree search and category filtering
- ✅ Session lifecycle (create, update, complete)
- ✅ Session export in multiple formats (markdown, text, HTML)
- ✅ Authorization and permission checking (engineer and admin roles)
### User Role Management Fix ✅
**Issue**: Registration endpoint was hardcoding all users as "engineer", preventing admin user creation in tests.
**Resolution**:
- Added `role` field to `UserCreate` schema with default="engineer"
- Updated registration endpoint to use `user_data.role` instead of hardcoding
- Enables proper role-based testing while maintaining secure defaults
- All 29 tests now pass successfully
### API Testing Results
Automated testing confirmed:
- **18/18 endpoints** fully functional
- **All authentication flows** working correctly
- **Tree management** complete (CRUD + search)
- **Session workflows** operational (with datetime fix)
- **Export functionality** validated (all 3 formats)
### Updated Project Structure
```text
backend/
├── alembic/ # Database migrations
├── app/
│ ├── api/ # API endpoints
│ ├── core/
│ │ ├── config.py
│ │ ├── database.py
│ │ ├── security.py
│ │ ├── logging_config.py # NEW: Logging setup
│ │ └── middleware.py # NEW: Request logging
│ ├── models/ # UPDATED: All datetime fields fixed
│ ├── schemas/
│ └── main.py # UPDATED: Logging integration
├── tests/ # NEW: Integration tests
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_trees.py
│ └── test_sessions.py
├── logs/ # NEW: Log files (created at runtime)
├── pytest.ini # NEW: Test configuration
└── requirements-dev.txt # NEW: Development dependencies
```
---
## How to Run the Backend
1. **Start PostgreSQL**:
```bash
cd backend
docker-compose up -d
```
2. **Set up Python environment**:
```bash
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # Linux/Mac
pip install -r requirements.txt
```
3. **Configure environment**:
```bash
cp .env.example .env
# Edit .env if needed (defaults work for local dev)
```
4. **Run database migrations**:
```bash
alembic upgrade head
```
5. **Start the development server**:
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
6. **Access API docs**: `http://localhost:8000/api/docs`
## How to Run Tests
1. **Install development dependencies**:
```bash
pip install -r requirements-dev.txt
```
2. **Create test database** (one-time setup):
```bash
# Connect to PostgreSQL
psql -U postgres -h localhost
# Create test database
CREATE DATABASE patherly_test;
\q
```
3. **Run all tests with coverage**:
```bash
cd backend
pytest
```
4. **Run specific test file**:
```bash
pytest tests/test_auth.py
```
5. **Run tests with verbose output**:
```bash
pytest -v
```
6. **View coverage report**:
```bash
# HTML report will be in htmlcov/index.html
open htmlcov/index.html # Mac/Linux
start htmlcov/index.html # Windows
```
---
## Phase 2: Frontend Implementation (COMPLETE)
### Tech Stack
- **Framework**: Vite + React 18 + TypeScript
- **Styling**: Tailwind CSS v3 + shadcn/ui CSS variables
- **State Management**: Zustand with persistence
- **Routing**: React Router v6
- **API Client**: Axios with token interceptors
### Frontend Structure
```
frontend/
├── src/
│ ├── api/ # API client layer
│ │ ├── client.ts # Axios instance with auth interceptors
│ │ ├── auth.ts # Auth endpoints
│ │ ├── trees.ts # Tree endpoints
│ │ └── sessions.ts # Session endpoints
│ ├── components/
│ │ └── layout/ # AppLayout, ProtectedRoute
│ ├── hooks/ # Custom hooks (future)
│ ├── lib/utils.ts # cn utility for class names
│ ├── pages/
│ │ ├── LoginPage.tsx
│ │ ├── RegisterPage.tsx
│ │ ├── TreeLibraryPage.tsx
│ │ ├── TreeNavigationPage.tsx # Core feature
│ │ ├── SessionHistoryPage.tsx
│ │ └── SessionDetailPage.tsx
│ ├── store/
│ │ └── authStore.ts # Zustand auth store
│ ├── types/ # TypeScript types
│ ├── App.tsx
│ ├── router.tsx
│ └── main.tsx
├── .env.example
├── tailwind.config.js
└── vite.config.ts
```
### Routes Implemented
| Path | Page | Auth Required |
|------|------|---------------|
| `/login` | LoginPage | No |
| `/register` | RegisterPage | No |
| `/trees` | TreeLibraryPage | Yes |
| `/trees/:id/navigate` | TreeNavigationPage | Yes |
| `/sessions` | SessionHistoryPage | Yes |
| `/sessions/:id` | SessionDetailPage | Yes |
### Key Features
- **JWT Auth**: Automatic token refresh on 401, persistent login state
- **Tree Library**: List/search/filter trees by category
- **Tree Navigation**: Full decision tree traversal with:
- Decision/Action/Solution node rendering
- Path breadcrumb navigation
- Back button support
- Notes per step
- Session completion
- **Session History**: View/resume sessions, filter by status
- **Export**: Download session transcript (Markdown/Text/HTML)
- **Error Handling**: Route-level ErrorBoundary for graceful error recovery
### Frontend Bug Fixes (January 28, 2026)
1. **CORS Configuration** - Added port 5174 to allowed origins in backend `.env` and `config.py`
2. **API Response Format** - Fixed `treesApi.list()` and `sessionsApi.list()` to expect arrays (not paginated objects)
3. **Session JSONB Serialization** - Fixed `model_dump(mode='json')` to properly serialize datetime fields for PostgreSQL JSONB storage
4. **ErrorBoundary Component** - Added `RouteError.tsx` for route-level error handling with "Go Back" / "Go Home" buttons
---
## How to Run the Frontend
1. **Start the backend** (in one terminal):
```bash
cd backend
venv\Scripts\activate
uvicorn app.main:app --reload
```
2. **Start the frontend** (in another terminal):
```bash
cd frontend
npm install
npm run dev
```
3. **Access the app**: http://localhost:5173
---
## Phase 2: Tree Editor (IN PROGRESS)
### Tree Editor Implementation
**Store**: `frontend/src/store/treeEditorStore.ts`
- Zustand with immer middleware for immutable updates
- zundo middleware for undo/redo functionality
- Node CRUD operations (add, update, delete)
- nodeMap for O(1) lookups
- Validation error tracking
**Components Created**:
| Component | Purpose |
|-----------|---------|
| `TreeEditorLayout.tsx` | Split-view container (editor 60%, preview 40%) |
| `TreeMetadataForm.tsx` | Tree name, description, category form |
| `NodeList.tsx` | List of nodes with add/edit/delete actions |
| `NodeEditorModal.tsx` | Modal wrapper for node editing |
| `NodeFormDecision.tsx` | Decision node fields (question, help_text, options) |
| `NodeFormAction.tsx` | Action node fields (title, description, commands) |
| `NodeFormResolution.tsx` | Solution node fields (title, steps) |
| `DynamicArrayField.tsx` | Reusable add/remove array input |
| `NodePicker.tsx` | Type-grouped dropdown for selecting next_node_id |
| `TreePreviewPanel.tsx` | Visual tree preview with SharedLinksMap |
| `TreePreviewNode.tsx` | Node cards with solution indicators |
| `MarkdownContent.tsx` | Reusable markdown renderer (react-markdown) |
**Routes Added**:
- `/trees/new` - Create new tree
- `/trees/:id/edit` - Edit existing tree
**Key Features**:
- Form-based editing with live preview
- NodePicker groups nodes by type (Decision/Action/Solution)
- Solution connection indicators (green checkmark badges)
- Shared node detection (shows when multiple nodes link to same target)
- Modal with scrollable content, fixed header/footer
- **Markdown preview toggle** in description fields
- **Markdown rendering** in session player (decision/action/solution descriptions)
---
## What's Next
### Phase 1b: Pre-built Trees (COMPLETE)
**Seed Data Scripts**:
- `backend/scripts/seed_data.py` - Original script
- `backend/scripts/seed_trees.py` - Comprehensive 7-tree seed script (NEW)
**Trees Implemented** (via `seed_trees.py`):
**Tier 1 - Help Desk:**
1. ✅ **Password Reset/Account Lockout** - Full implementation (~20 nodes)
2. ✅ **Outlook/Email Problems** - Complete with MAPI profile, OST, and connectivity checks
3. ✅ **VPN Connection Failures** - GlobalProtect, Cisco AnyConnect troubleshooting
4. ✅ **Printer Problems** - Print queue, driver, spooler, network printer diagnostics
**Tier 2 - Desktop Support:**
5. ✅ **Slow Computer Troubleshooting** - Startup, disk, RAM, malware diagnostics
6. ✅ **Network Connectivity Issues** - IP config, DNS, gateway, firewall checks
**Tier 3 - Systems:**
7. ✅ **File Share Access Problems** - Full implementation with NTFS, share permissions, DFS checks
**Each tree features:**
- 10-20+ nodes with realistic branching
- Real PowerShell commands in action nodes
- Professional ticket documentation guidance in solution nodes
- Markdown-formatted descriptions
### Remaining Work
1. **Tree Editor Polish**: Validation, required fields, orphan detection
2. ~~**User Preferences**: Dark mode, export format defaults~~ Dark mode **COMPLETE**, export format pending
3. ~~**More Trees**: Add remaining 4 trees from `TS-EXAMPLES.md`~~ **COMPLETE** - 7 comprehensive trees seeded
4. **Deployment**: Set up CI/CD pipeline and deploy to Render/Railway
---
## Important Files to Reference
| File | Purpose |
|------|---------|
| `02-TECHNICAL-ARCHITECTURE.md` | Full technical spec (database schema, API endpoints) |
| `05-QUESTIONS-AND-ACTION-ITEMS.md` | Design decisions and priorities |
| `TS-EXAMPLES.md` | 5 example troubleshooting trees to implement |
| `backend/README.md` | Backend setup instructions |
| `frontend/.env.example` | Frontend environment template |
---
## Notes for Next Session
- ✅ Backend **fully tested** - all 18 endpoints working correctly
- ✅ **Integration tests** - 40+ tests with full coverage (all passing)
- ✅ **Frontend COMPLETE** - Full React app with all core pages
- ✅ **Tree Editor IMPLEMENTED** - Form-based editing with visual preview
- ✅ **Markdown Rendering** - Session player and node editor support markdown
- ✅ **7 Seed Trees** - Comprehensive troubleshooting trees across Tier 1/2/3
- ✅ **Full workflow tested** - Register → Login → Browse → Navigate → Complete → Export all working
- 📝 **Single-user focus** for MVP (team features are in schema but low priority)
### Recommended Next Steps
1. ~~**User Preferences**: Dark mode toggle~~ **COMPLETE**
2. **Tree Editor Validation**: Required fields, orphan node detection, save validation
3. **Deploy**: Set up CI/CD pipeline and deploy to Render/Railway
4. **Real-world Testing**: Use on actual support tickets
### Recent Additions (Jan 29, 2026)
1. **Seed Script** (`backend/scripts/seed_trees.py`) - 7 comprehensive troubleshooting trees
2. **Markdown Rendering** - `react-markdown` package + `MarkdownContent` component
3. **Preview Toggle** - Description fields in node editor can toggle between edit/preview
4. **LESSONS-LEARNED.md** updated with httpx and email validation fixes