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

docs: rewrite README and add CHANGELOG

Browse Source 
README: updated to reflect current product (FlowPilot, PSA integration,
Knowledge Flywheel), fixed stale roadmap references to closed issues,
corrected Tailwind version (v3→v4), added Quick Start section, linked
all documentation.

CHANGELOG: organized by version from v0.1.0 (Jan 2026) through v0.9.0
(current), covering all major features across 9 releases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
chihlasm
2026-03-21 16:26:52 +00:00
parent 8e2332bc51
commit a9717951f0
2 changed files with 223 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
CHANGELOG.md Normal file
View File

@@ -0,0 +1,139 @@
# Changelog
All notable changes to ResolutionFlow are documented here.
## [Unreleased]
### Added
- Tree Templates + Import/Export marketplace (#66)
- Recurring Issue Detection — client-specific pattern alerts (#60)
- Step Feedback Flag — "This Step is Wrong" reporting (#58)
---
## [0.9.0] - 2026-03-21
### Added
- **Landing page design audit** — mobile hamburger menu, Privacy and Terms pages, responsive modals
- **Mobile search collapse** — TopBar search bar collapses to magnifying glass icon on mobile
- **Root directory cleanup** — archived 9 completed docs, tracked marketing assets and dev environment guide
### Changed
- Branding updated: "Decision Tree Platform" → "AI-Powered Troubleshooting for MSPs" on login, register, HTML title
- Section spacing tightened on landing page, heading hierarchy fixed (div → h2)
- Register page icon fixed from red/coral to cyan brand color
- `transition: all` replaced with specific properties across landing CSS
- `color-scheme: dark` added to HTML element
- GitHub issues triaged: closed 10 stale issues (6 completed, 4 deferred), 3 remain open
---
## [0.8.0] - 2026-03-20
### Added
- **FlowPilot cockpit dashboard** — quick-start input, active sessions, pending escalations, performance cards, knowledge base cards, team summary
- **Sidebar redesign** — Dashboard → Resolve → Knowledge → Insights hierarchy with collapsible sections
- **Search & Recall** — PostgreSQL FTS on AI sessions, Command Palette integration (Ctrl+K), structured filters
- **Semantic similar sessions** — Voyage AI embeddings for finding related past sessions in FlowPilot sidebar
- **Evidence-rich sessions** — RichTextInput with clipboard paste, S3 file upload/download API
- **Navigation guard** — `useBlocker` warns before leaving active FlowPilot sessions
### Fixed
- FlowPilot action bar height chain (Resolve/Escalate/Pause buttons disappearing)
- `InFailedSQLTransaction` cascade from `get_db` missing rollback
- Session detail 500 errors from serialization issues
- Escalation fallback when `team_id` is null
- CORS middleware returning proper responses instead of re-raising
---
## [0.7.0] - 2026-03-19
### Added
- **Phase 5 Analytics Enhancement** — flow coverage heatmap, quality scoring, PSA activity logging, enhanced metrics
- **Phase 4 Enterprise features** — public templates gallery, admin curation, branded exports, custom branding (logo, accent, company name), multi-PSA adapter stubs (Autotask, Halo), SSO/SAML groundwork
- **Notification system** — multi-channel (in-app, email) with preferences and batch digest
### Fixed
- Analytics domain matching, funnel counts, decimal casts
- Frontend routing, accessibility, error states, sort indicators
---
## [0.6.0] - 2026-03-18
### Added
- **FlowPilot Phase 1** — AI-powered troubleshooting sessions with guided multi-step engine, copilot panel, confidence-tiered model routing
- **FlowPilot Phase 2** — ConnectWise PSA integration (ticket linking, note posting, member mapping), escalation handoff with AI-enhanced briefing, session pause/resume, mid-session ticket linking
- **Knowledge Flywheel (Phase 3)** — AI session analysis → automatic flow proposals, review queue (approve, edit & publish, dismiss, reject), knowledge gap detection, FlowPilot analytics dashboard, APScheduler batch analysis
---
## [0.5.0] - 2026-03-16
### Added
- **Security headers** — CSP (report-only), HSTS, X-Content-Type-Options, X-Frame-Options
- **Coverage gates** — 80% backend coverage enforced in CI, frontend coverage reporting
- **Core Web Vitals** — LCP, FID, CLS reporting to PostHog
- **PostHog analytics** — event tracking across all key user actions, user identification, autocapture
- **Playwright e2e tests** — coverage for new features and uncovered workflows
- **Command palette** — global search (Ctrl+K) with fuzzy matching across flows, sessions, tags
---
## [0.4.0] - 2026-03-14
### Added
- **ConnectWise PSA integration design** — provider abstraction, encrypted credentials, ticket context
- **Script Generator** — backend engine, API, frontend template editor, parameter detector
- **Procedural editor validation** — validation summary with click-to-select and Fix with AI
- **Landing page** — marketing site with beta signup, pricing tiers, product preview mockup
---
## [0.3.0] - 2026-03-03
### Added
- **Slate & Ice design system** — dark glassmorphism, ice-cyan gradient accents, glass-card system, orchestrated animations
- **Tailwind CSS v4 migration** — CSS-only config, `@tailwindcss/vite` plugin
- **KB Accelerator** — convert knowledge base articles into interactive flows
- **AI chat conclusion** — outcome tracking, AI-generated ticket summaries, resume flow
- **Survey system** — public survey page, admin invite tracking, response viewer with CSV export
- **Email verification** — tokens, banner, admin toggle
- **AI assistant** — in-session copilot panel, standalone chat with RAG, prompt caching
- **Sentry error monitoring** — frontend and backend integration
- **Flexible intake** — deferred variables, prepared sessions
- **Session closure** — close from history page with inline popover
- **Shared Modal enforcement** — standardized modal component across codebase
### Fixed
- Race condition hardening across auth, counters, and data fetching
- MissingGreenlet crash in AI Assistant
---
## [0.2.0] - 2026-02-10
### Added
- **Flow Editor** — form-based with visual canvas preview (React Flow + dagre), undo/redo
- **Procedural Flows** — step-by-step checklists with section headers, collapsible fields
- **Maintenance Flows** — scheduled recurring tasks with batch execution
- **AI Flow Builder** — conversational AI generates complete flows from description
- **Step Library** — shared reusable steps with ratings, reviews, verified-use badges
- **Session features** — timer, keyboard shortcuts, scratchpad overlay, auto-recovery, sharing
- **Organization** — categories, tags, folders (3-level), full-text search, grid/list/table views
- **Admin Panel** — 8 pages (dashboard, users, invite codes, audit logs, plan limits, feature flags, settings, categories)
- **Account management** — profile settings, delete/leave/transfer, chat retention
- **Export** — Markdown, text, HTML with detail levels, editable preview, redaction
---
## [0.1.0] - 2026-01-15
### Added
- Initial release: FastAPI backend with JWT auth, PostgreSQL database
- Trees and Sessions CRUD APIs
- Export functionality (Markdown, Text, HTML)
- React frontend with TypeScript
- Railway deployment with auto-deploy on push to main
- Invite code registration system for beta

194
README.md
View File

@@ -1,76 +1,84 @@
# ResolutionFlow
> Take the path MOST traveled.
> Stop writing ticket notes. Start generating them.
**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.
**ResolutionFlow** is an AI-powered troubleshooting platform for MSP professionals. Engineers follow guided flows while an AI copilot assists — and documentation writes itself as a byproduct of the work.
**Production:** [resolutionflow.com](https://resolutionflow.com)
---
## The Problem
## Quick Start
MSP engineers face constant context switching between diverse technical issues — file shares, server outages, VPN failures, Active Directory problems. This creates:
```bash
# Prerequisites: Docker, Python 3.11+, Node.js 20+
- **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
# Start PostgreSQL
docker start patherly_postgres
## The Solution
# Backend
cd backend
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload
An intelligent flow system that:
# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```
- **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
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api/docs
See [DEV-ENV.md](DEV-ENV.md) for full environment setup (devserver, Docker, CORS).
---
## Features
### Flow Types
### FlowPilot AI Copilot
Like having a senior engineer on every call. FlowPilot guides troubleshooting decisions, suggests next steps with context-aware intelligence, and automatically captures documentation as a byproduct of the session.
- Confidence-tiered model routing (fast responses for simple steps, deeper reasoning for complex decisions)
- AI-generated ticket summaries and session documentation
- Standalone assistant chat with RAG for open-ended troubleshooting
- Knowledge Flywheel: AI analyzes completed sessions and proposes new flows automatically
### Guided Flows
- **Troubleshooting Flows** — Decision trees with branching paths for diagnosing issues
- **Procedural Flows (Projects)** — Step-by-step checklists for structured processes (onboarding, migrations, deployments)
- **Procedural Flows (Projects)** — Step-by-step checklists for onboarding, migrations, deployments
- **Maintenance Flows** — Scheduled recurring tasks with batch execution across multiple targets
- Visual Flow Editor with drag-and-drop canvas, undo/redo, markdown support
- AI Flow Builder — describe what you need, get a complete flow generated
### 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
### Auto-Documentation
### 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
Every session generates timestamped, detailed notes formatted for your PSA. Engineers never write another ticket note.
### 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
- Export to Markdown, plain text, or HTML
- Sensitive data redaction
- One-click push to ConnectWise PSA tickets
### ConnectWise PSA Integration
- Post session documentation directly to ConnectWise tickets as internal notes
- Pull ticket details and client context into FlowPilot sessions
- Member mapping between ResolutionFlow and ConnectWise users
- Credentials encrypted at rest (Fernet), stored per-team
### Team & Knowledge Management
- Role-based access (super_admin, team_admin, engineer, viewer)
- Shared flow library with categories, tags, folders, full-text search
- Step Library — reusable troubleshooting steps with ratings and reviews
- 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
- Escalation workflow with AI-enhanced briefing packages
- Flow proposals from AI analysis (review queue for team leads)
---
@@ -78,16 +86,18 @@ An intelligent flow system that:
| Layer | Technology |
|-------|------------|
| Frontend | React 19, TypeScript, Vite, Tailwind CSS v3 |
| Frontend | React 19, TypeScript, Vite, Tailwind CSS v4 |
| 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 |
| Migrations | Alembic (75+ migrations) |
| Auth | JWT (python-jose) + bcrypt, refresh token rotation |
| AI | Anthropic Claude API |
| AI | Anthropic Claude API (tiered model routing) |
| Embeddings | Voyage AI (semantic search) |
| Scheduling | APScheduler 3.x (async) |
| Analytics | PostHog |
| Hosting | Railway (auto-deploy on push to main) |
---
@@ -99,88 +109,52 @@ 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
│ │ ├── api/endpoints/ # Route handlers (35+ endpoints)
│ │ ├── core/ # Config, database, permissions, security
│ │ ├── models/ # SQLAlchemy models
│ │ └── schemas/ # Pydantic schemas
│ │ ├── schemas/ # Pydantic schemas
│ │ └── services/psa/ # PSA provider abstraction layer
│ ├── alembic/ # Database migrations
│ ├── scripts/ # Seed data scripts
│ └── tests/ # pytest integration tests (100+)
│ └── tests/ # 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
├── docs/ # Design docs, plans, ConnectWise reference
├── brand-assets/ # SVGs, brand guide
├── CLAUDE.md # AI assistant project context
├── CURRENT-STATE.md # Detailed feature status
├── 03-DEVELOPMENT-ROADMAP.md # Development roadmap
└── docs/plans/ # Design docs & implementation plans
└── CHANGELOG.md # Release history
```
---
## Development Setup
### Prerequisites
- Docker (for PostgreSQL)
- Python 3.11+
- Node.js 18+
### Quick Start
## Running Tests
```bash
# Start PostgreSQL
docker start patherly_postgres
# Backend
# Backend integration tests
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
# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```
### URLs
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api/docs
### Running Tests
```bash
# Backend (from backend/)
pytest --override-ini="addopts="
# Frontend type check
cd frontend && npm run build
# Frontend build (stricter than tsc --noEmit)
cd frontend
npm run build
```
---
## Roadmap
## Documentation
See [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) for the full roadmap.
**Current focus:**
- Step Library frontend UI
- Procedural flows lifecycle improvements
**Next up:**
- Quick Actions Dashboard (#70)
- Tree Effectiveness Dashboard (#61)
- PSA Integration — ConnectWise / Autotask (#63)
| Document | Purpose |
|----------|---------|
| [CLAUDE.md](CLAUDE.md) | Full project context for AI-assisted development |
| [CURRENT-STATE.md](CURRENT-STATE.md) | Detailed feature status |
| [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) | Development roadmap |
| [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md) | Design system (Slate & Ice) |
| [DEV-ENV.md](DEV-ENV.md) | Development environment setup |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
---