chihlasm/resolutionflow
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
52e8190211b465cc57df94624c6cfe7cc7a82b4b
resolutionflow/04-FEATURE-SPECIFICATIONS.md
Michael Chihlas 52e8190211 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

18 KiB
Raw Blame History

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:

"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

# 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:

{
  "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:

{
  "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"
Reference in New Issue View Git Blame Copy Permalink