diff --git a/README.md b/README.md index 42f0c800..edc9d261 100644 --- a/README.md +++ b/README.md @@ -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.