From a9717951f014f09fc62d5a5d0545384dc5b8f9a0 Mon Sep 17 00:00:00 2001 From: chihlasm Date: Sat, 21 Mar 2026 16:26:52 +0000 Subject: [PATCH] docs: rewrite README and add CHANGELOG MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- CHANGELOG.md | 139 ++++++++++++++++++++++++++++++++++++ README.md | 194 ++++++++++++++++++++++----------------------------- 2 files changed, 223 insertions(+), 110 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..1ee18403 --- /dev/null +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index edc9d261..482f49ef 100644 --- a/README.md +++ b/README.md @@ -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 | ---