c2c126d0cd
- Use envsubst to inject PORT at runtime
- Template nginx.conf with ${PORT} placeholder
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Patherly
Take the path MOST traveled.
Project Status: 🚀 Phase 2 - Active Development
Backend: Complete and tested (18 API endpoints, 40+ integration tests) Frontend: Core features complete, Tree Editor in progress Tree Editor: Visual editor with form-based editing and live preview panel
The Problem
MSP engineers face constant context switching between diverse technical issues (file shares, server outages, VPN failures, Active Directory problems). This creates:
- Cognitive overload: 15-25 minutes to regain focus after each context switch
- Inconsistent documentation: Under pressure, notes are rushed or incomplete
- Lost tribal knowledge: Best troubleshooting paths live only in senior engineers' heads
- Repeated work: Same issues investigated from scratch each time
- Burnout: Research shows context switching is a major contributor to burnout
The Solution
An intelligent decision tree system that:
✅ Guides engineers through proven troubleshooting paths
✅ Captures decisions and notes automatically as you work
✅ Generates professional ticket documentation with one click
✅ Builds institutional knowledge that improves over time
✅ Reduces cognitive load during high-stress situations
Success Metric
If Michael (our primary user) uses this tool for 50% of his tickets in 3 months, we've succeeded.
Key Features
MVP (Weeks 1-3)
- 🌳 Tree Navigation - Step-by-step guided troubleshooting
- 📝 Automatic Notes - Capture context at each decision point
- 📄 Export - Generate professional documentation (plain text, markdown, HTML)
- 🔐 Multi-User - Team authentication and access control
- 📚 Documentation Links - Contextual links to KB articles and vendor docs
Phase 2 (Weeks 4-6)
- 👥 Team Management - Controlled authorship, shared access
- ✏️ Tree Editor - Visual interface to create/modify decision trees
- 📱 Mobile Responsive - Works on phone/tablet for on-site work
- 🔀 Custom Branches - Add unique steps on-the-fly during troubleshooting
- 🔍 Search & Categories - Find the right tree quickly
Phase 3 (Weeks 7-12)
- 📎 Attachments - Upload screenshots, logs, command outputs
- 💾 Offline Mode - Continue working without internet, sync when back online
- 🏢 Client Context - Auto-fill client-specific details (server names, topologies)
- 📧 Send to Engineer - Generate simplified checklist for onsite techs
- 📊 Analytics - Track usage, common paths, team performance
Phase 4 (Months 4-6)
- 🔌 API & Integrations - Connect to ConnectWise, Kaseya, LabTech
- ⚡ Automation - Execute PowerShell scripts directly from trees
- 🏢 Enterprise Features - SSO, white-labeling, advanced RBAC
- 🌐 Marketplace - Share and discover community-contributed trees
Tech Stack
Frontend
- React - Modern, flexible, excellent offline support
- Tailwind CSS - Rapid UI development
- Service Workers - Offline capability
- IndexedDB - Local data storage
Backend
- Python FastAPI - Modern, fast, async support
- SQLAlchemy - ORM with async support
- PostgreSQL - Reliable database with excellent JSON support
- Alembic - Database migrations
Infrastructure
- S3-Compatible Storage - File attachments (MinIO for dev, S3/Spaces for prod)
- Railway/Render - Simple hosting to start
- Docker - Containerized development environment
Project Structure
troubleshooting-tree-app/
├── docs/
│ ├── 01-PROJECT-OVERVIEW.md # Vision, goals, market analysis
│ ├── 02-TECHNICAL-ARCHITECTURE.md # System design, data models, API specs
│ ├── 03-DEVELOPMENT-ROADMAP.md # Phases, timeline, milestones
│ ├── 04-FEATURE-SPECIFICATIONS.md # Detailed feature descriptions
│ └── 05-QUESTIONS-AND-ACTION-ITEMS.md # Decisions needed, next steps
├── backend/ # Python FastAPI application (future)
├── frontend/ # React application (future)
├── database/ # Database schemas, migrations (future)
└── README.md # This file
Getting Started
For Michael (Primary User)
Immediate Action Items:
-
Answer Key Questions (see
docs/05-QUESTIONS-AND-ACTION-ITEMS.md)- Timeline needs
- Budget for hosting
- Team size
- Branding preferences
-
Document 5 Troubleshooting Scenarios
- Citrix VDA Not Registering
- FSLogix Profile Issues
- Active Directory Replication Failure
- SonicWall VPN Tunnel Down
- User Unable to Access File Share
See template in
05-QUESTIONS-AND-ACTION-ITEMS.md -
Provide Sample Export
- Show how you currently write ticket notes
- What format/level of detail is needed
-
Review Documentation
- Read through all docs in
docs/folder - Flag anything unclear or that you disagree with
- Add your own thoughts/ideas
- Read through all docs in
For Developers (Future)
Once development starts:
- Clone repository
- Set up development environment (Docker)
- Install dependencies
- Run migrations
- Start development servers
- See
CONTRIBUTING.mdfor coding standards
Development Principles
- User First - Every feature must solve a real problem for Michael and his team
- Speed Matters - Tool must be faster than doing it manually
- Progressive Enhancement - Start simple, add complexity only when needed
- Offline Capable - Many MSP sites have poor connectivity
- Automation-Ready - Architecture supports future integration with scripts/tools
- Documentation Over Memory - Capture tribal knowledge explicitly
- Fail Gracefully - Never lose user's work, even if server fails
Use Cases
Scenario 1: Standard Troubleshooting
Michael gets a ticket: "User can't access file share"
- Opens app, selects "File Share Access Issues" tree
- Enters ticket number, client name
- Follows decision tree, making selections and adding notes
- Reaches resolution in 10 minutes
- Clicks "Export", copies formatted notes into ticket
- Done - professional documentation with zero extra effort
Scenario 2: Complex Multi-Step Issue
Michael troubleshooting Citrix VDA registration failure
- Starts with "VDA Not Registering" tree
- Discovers network issue, branches to "Network Connectivity" tree
- Finds firewall blocking traffic, attaches screenshot of rule
- Returns to VDA tree, continues troubleshooting
- Automation script restarts services, captures output
- VDA registers successfully
- Exports comprehensive notes showing entire diagnostic path
Scenario 3: Junior Engineer Learning
New engineer Sarah gets escalated Active Directory issue
- Selects "AD Replication Failure" tree (created by Michael)
- Tree guides her step-by-step with commands to run
- At each step, links to Microsoft Learn docs explain concepts
- She adds detailed notes about what she found
- Reaches point requiring senior help, shares session link with Michael
- Michael reviews her work, sees exactly what she tried
- Guides her through final steps over Slack
- Sarah learns the process, documents it properly
Scenario 4: On-Site Technician
Michael needs hands at a remote site
- Creates troubleshooting plan in app
- Clicks "Send to Engineer", generates simplified checklist
- Sends link to on-site tech via text
- Tech follows steps, checks boxes, adds photos of error messages
- Reports back results in real-time
- Michael adjusts plan remotely if needed
- Issue resolved with minimal back-and-forth
Why This Could Be Special
For Individual Engineers
- Save 30+ minutes per complex ticket
- Never lose track of troubleshooting progress
- Professional documentation every time
- Learn from experienced engineers' approaches
- Build personal knowledge base over time
For MSP Teams
- Standardize troubleshooting procedures
- Onboard junior engineers faster
- Capture institutional knowledge before engineers leave
- Improve ticket documentation quality
- Identify training gaps and common issues
- Track team performance and efficiency
For the Market
- 30,000+ MSPs in North America alone
- Adjacent markets: Internal IT, DevOps, Technical Support
- Current solutions are either too generic (flowchart tools) or too rigid (static runbooks)
- Unique Value: Purpose-built for technical troubleshooting with automation integration
Potential Business Model
- Free Tier: Personal use, limited trees
- Pro Tier: $15-25/user/month - Team features, unlimited trees, analytics
- Enterprise: Custom pricing - API, SSO, white-labeling
- Marketplace: Revenue share on community trees
- Professional Services: Custom tree development, training, consulting
Inspiration & Similar Tools
What Exists Today
- ServiceNow Knowledge Base - Good for static docs, not interactive troubleshooting
- IT Glue - Documentation repository, not a troubleshooting guide
- Confluence Decision Trees - Generic flowcharts, not execution-focused
- Custom Runbooks - Static, not adaptive, no automation
What We're Building
Imagine if ServiceNow Knowledge, Flowchart tools, and PowerShell automation had a baby specifically designed for MSP troubleshooting. That's this.
FAQ
Q: Why not just use a wiki or documentation system?
A: Wikis are great for reference, but they don't guide you through troubleshooting in real-time or automatically generate ticket notes from your actions.
Q: Won't creating trees take more time than just doing the work?
A: Initially, yes. But after 2-3 uses of a tree, you've saved more time than you spent creating it. Plus, the tree captures knowledge that helps the entire team.
Q: What if the tree doesn't cover my specific issue?
A: You can add custom branches on-the-fly during troubleshooting. These custom paths can then be incorporated into the tree for next time.
Q: How is this different from a flowchart tool?
A: Flowcharts are static diagrams. This is an active troubleshooting companion that captures your work and generates documentation.
Q: Can I use this offline?
A: Yes (Phase 3). Trees are cached locally, you can work offline, and changes sync when you're back online.
Q: Will this replace my ticketing system?
A: No, it complements it. You still create tickets in your PSA, but this generates the detailed notes you paste into tickets.
Q: Can I automate steps?
A: Yes (Phase 4). Integrate PowerShell scripts and other automation that can be triggered directly from decision nodes.
Contributing
This is currently a private project in planning phase. Once we move to active development, we'll create a CONTRIBUTING.md with:
- Code of conduct
- Development workflow
- Coding standards
- Testing requirements
- PR process
Contact & Feedback
Primary User: Michael Chihlas
Project Lead: [To be determined]
Communication: [To be determined]
For questions, suggestions, or to get involved, contact Michael.
License
[To be determined]
Options being considered:
- Open source (MIT/Apache 2.0) - maximize adoption
- Source-available with commercial license - protect business interests
- Proprietary - if building as commercial product
Acknowledgments
- Research on context switching and burnout that inspired this project
- MSP community for sharing their pain points and workflows
- All the engineers who've struggled with documentation and wished for a better way
Roadmap at a Glance
└─ [✅ Planning] COMPLETE
├─ ✅ Document requirements
├─ ✅ Make key decisions
└─ ✅ Setup initial architecture
└─ [✅ Phase 1: MVP] COMPLETE
├─ ✅ Backend API (18 endpoints)
├─ ✅ Tree navigation UI
├─ ✅ Session tracking
└─ ✅ Export functionality
└─ [🚀 Phase 2: Team Ready] ← IN PROGRESS
├─ ✅ Tree Editor (form-based with preview)
├─ ⏳ Team management
└─ ⏳ Mobile responsive
└─ [📋 Phase 3: Professional]
├─ Attachments
├─ Offline mode
└─ Analytics
└─ [📋 Phase 4: Platform]
├─ API & integrations
├─ Automation
└─ Enterprise features
Last Updated: 2026-01-28 Project Status: Phase 2 - Active Development Next Milestone: Complete Tree Editor polishing, Team management features