Initial commit: Backend API Phase 1a complete

- FastAPI backend with JWT auth - PostgreSQL database schema - Trees and Sessions CRUD APIs - Export functionality (Markdown, Text, HTML) - Docker setup for local development - Alembic migrations
2026-01-22 14:38:53 -05:00
commit 52e8190211
42 changed files with 5385 additions and 0 deletions
--- a/04-FEATURE-SPECIFICATIONS.md
+++ b/04-FEATURE-SPECIFICATIONS.md
@@ -0,0 +1,606 @@
+# 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. 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)
+
+---
+
+## Feature Priority Matrix
+
+| Feature | MVP | Phase 2 | Phase 3 | Phase 4 |
+|---------|-----|---------|---------|---------|
+| Tree Navigation | ✓ | | | |
+| Basic Export | ✓ | | | |
+| User Auth | ✓ | | | |
+| 5 Starter Trees | ✓ | | | |
+| Team Management | | ✓ | | |
+| Tree Editor | | ✓ | | |
+| Mobile Responsive | | ✓ | | |
+| Custom Branches | | ✓ | | |
+| 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"