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

docs: rewrite README to reflect current product state

Browse Source 
Updated from planning-phase placeholder to accurate representation of
ResolutionFlow as a production SaaS product. Reflects all shipped features
(AI Flow Assist, procedural/maintenance flows, cross-references, session
sharing, export improvements), current tech stack, project structure, and
development setup instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
chihlasm
2026-03-01 00:36:23 -05:00
parent 459792019a
commit 9bef7e5814
1 changed files with 132 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
README.md
View File

@@ -2,350 +2,188 @@
> Take the path MOST traveled.
## Project Status: 🚀 Phase 2 - Active Development
**ResolutionFlow** is a SaaS platform for MSP professionals that provides guided troubleshooting flows, captures decisions and notes as you work, and generates professional ticket documentation with one click.
**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
**Production:** [resolutionflow.com](https://resolutionflow.com)
---
## The Problem
MSP engineers face constant context switching between diverse technical issues (file shares, server outages, VPN failures, Active Directory problems). This creates:
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
- **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
## The Solution
An intelligent decision tree system that:
An intelligent flow 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.
- **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
---
## Key Features
## 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
### Flow Types
- **Troubleshooting Flows** — Decision trees with branching paths for diagnosing issues
- **Procedural Flows (Projects)** — Step-by-step checklists for structured processes (onboarding, migrations, deployments)
- **Maintenance Flows** — Scheduled recurring tasks with batch execution across multiple targets
### 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
### Flow Editor
- Form-based node editor with live canvas preview (React Flow + dagre layout)
- Decision nodes (yes/no, multiple choice), action nodes, answer nodes
- Cross-reference / loop-back support — link any node to any other node for re-verification patterns
- Undo/redo, validation warnings, drag-to-reorder
- Markdown support in descriptions and help text
### 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
### AI Flow Assist
- Conversational AI builder — describe what you need, get a complete flow generated
- Multi-phase interview (scope, structure, details) with progressive tree generation
- Live preview updates as the AI builds your flow
- Save directly to your flow library
### 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
### Session Engine
- Step-by-step guided navigation with notes capture at each decision point
- Session timer, keyboard shortcuts, scratchpad overlay (Ctrl+/)
- Auto-recovery for interrupted sessions
- Session sharing via link (authenticated and public views)
- Export to Markdown, plain text, or HTML with configurable detail levels, editable preview, and sensitive data redaction
### Organization & Management
- Categories, tags (autocomplete), user folders (3-level hierarchy)
- Full-text search across all flows
- Pinned flows for quick access
- Grid, list, and table views
### Team & Admin
- Role-based access control (super_admin, team_admin, engineer, viewer)
- Admin panel — user management, invite codes, audit logs, feature flags, plan limits
- Team-scoped visibility and permissions
### Step Library
- Shared library of reusable troubleshooting steps
- Search, ratings, reviews, verified-use badges
- Private, team, and public visibility levels
---
## 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
| Layer | Technology |
|-------|------------|
| Frontend | React 19, TypeScript, Vite, Tailwind CSS v3 |
| State | Zustand (immer + zundo for undo/redo) |
| Routing | React Router v7 |
| Canvas | @xyflow/react (React Flow) + dagre |
| Backend | Python FastAPI, async SQLAlchemy 2.0 + asyncpg |
| Database | PostgreSQL 16 |
| Migrations | Alembic |
| Auth | JWT (python-jose) + bcrypt, refresh token rotation |
| AI | Anthropic Claude API |
| Scheduling | APScheduler 3.x (async) |
| Hosting | Railway (auto-deploy on push to main) |
---
## 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
patherly/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI entry point
│ │ ├── api/endpoints/ # Route handlers
│ │ ├── api/deps.py # Auth dependencies
│ │ ├── api/router.py # Route registration
│ │ ├── core/ # Config, database, permissions, security, AI services
│ │ ├── models/ # SQLAlchemy models
│ │ └── schemas/ # Pydantic schemas
│ ├── alembic/ # Database migrations
│ ├── scripts/ # Seed data scripts
│ └── tests/ # pytest integration tests (100+)
├── frontend/
│ ├── src/
│ │ ├── api/ # Axios client + endpoint modules
│ │ ├── components/ # UI components by domain
│ │ ├── hooks/ # Custom React hooks
│ │ ├── pages/ # Page components
│ │ ├── store/ # Zustand stores
│ │ └── types/ # TypeScript interfaces
│ └── tailwind.config.js
├── CLAUDE.md # AI assistant project context
├── CURRENT-STATE.md # Detailed feature status
├── 03-DEVELOPMENT-ROADMAP.md # Development roadmap
└── docs/plans/ # Design docs & implementation plans
```
---
## Getting Started
## Development Setup
### For Michael (Primary User)
### Prerequisites
- Docker (for PostgreSQL)
- Python 3.11+
- Node.js 18+
**Immediate Action Items:**
### Quick Start
1. **Answer Key Questions** (see `docs/05-QUESTIONS-AND-ACTION-ITEMS.md`)
- Timeline needs
- Budget for hosting
- Team size
- Branding preferences
```bash
# Start PostgreSQL
docker start patherly_postgres
2. **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
# Backend
cd backend
python -m venv venv
source venv/bin/activate # or .\venv\Scripts\Activate on Windows
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload
See template in `05-QUESTIONS-AND-ACTION-ITEMS.md`
# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```
3. **Provide Sample Export**
- Show how you currently write ticket notes
- What format/level of detail is needed
### URLs
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api/docs
4. **Review Documentation**
- Read through all docs in `docs/` folder
- Flag anything unclear or that you disagree with
- Add your own thoughts/ideas
### Running Tests
### For Developers (Future)
```bash
# Backend (from backend/)
pytest --override-ini="addopts="
Once development starts:
1. Clone repository
2. Set up development environment (Docker)
3. Install dependencies
4. Run migrations
5. Start development servers
6. See `CONTRIBUTING.md` for coding standards
# Frontend type check
cd frontend && npm run build
```
---
## Development Principles
## Roadmap
1. **User First** - Every feature must solve a real problem for Michael and his team
2. **Speed Matters** - Tool must be faster than doing it manually
3. **Progressive Enhancement** - Start simple, add complexity only when needed
4. **Offline Capable** - Many MSP sites have poor connectivity
5. **Automation-Ready** - Architecture supports future integration with scripts/tools
6. **Documentation Over Memory** - Capture tribal knowledge explicitly
7. **Fail Gracefully** - Never lose user's work, even if server fails
See [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) for the full roadmap.
---
**Current focus:**
- Step Library frontend UI
- Procedural flows lifecycle improvements
## Use Cases
### Scenario 1: Standard Troubleshooting
Michael gets a ticket: "User can't access file share"
1. Opens app, selects "File Share Access Issues" tree
2. Enters ticket number, client name
3. Follows decision tree, making selections and adding notes
4. Reaches resolution in 10 minutes
5. Clicks "Export", copies formatted notes into ticket
6. Done - professional documentation with zero extra effort
### Scenario 2: Complex Multi-Step Issue
Michael troubleshooting Citrix VDA registration failure
1. Starts with "VDA Not Registering" tree
2. Discovers network issue, branches to "Network Connectivity" tree
3. Finds firewall blocking traffic, attaches screenshot of rule
4. Returns to VDA tree, continues troubleshooting
5. Automation script restarts services, captures output
6. VDA registers successfully
7. Exports comprehensive notes showing entire diagnostic path
### Scenario 3: Junior Engineer Learning
New engineer Sarah gets escalated Active Directory issue
1. Selects "AD Replication Failure" tree (created by Michael)
2. Tree guides her step-by-step with commands to run
3. At each step, links to Microsoft Learn docs explain concepts
4. She adds detailed notes about what she found
5. Reaches point requiring senior help, shares session link with Michael
6. Michael reviews her work, sees exactly what she tried
7. Guides her through final steps over Slack
8. Sarah learns the process, documents it properly
### Scenario 4: On-Site Technician
Michael needs hands at a remote site
1. Creates troubleshooting plan in app
2. Clicks "Send to Engineer", generates simplified checklist
3. Sends link to on-site tech via text
4. Tech follows steps, checks boxes, adds photos of error messages
5. Reports back results in real-time
6. Michael adjusts plan remotely if needed
7. 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.
**Next up:**
- Quick Actions Dashboard (#70)
- Tree Effectiveness Dashboard (#61)
- PSA Integration — ConnectWise / Autotask (#63)
---
## 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
Proprietary. All rights reserved.