resolutionflow/README.md

# ResolutionFlow

> Stop writing ticket notes. Start generating them.

**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)

---

## Quick Start

```bash
# Prerequisites: Docker, Python 3.12, Node.js 20+

# Start PostgreSQL (and the rest of the dev stack)
docker compose -f docker-compose.dev.yml up -d

# Backend
cd backend
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```

- 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

### 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 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

### Auto-Documentation

Every session generates timestamped, detailed notes formatted for your PSA. Engineers never write another ticket note.

- 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)
- Escalation workflow with AI-enhanced briefing packages
- Flow proposals from AI analysis (review queue for team leads)

---

## Tech Stack

| Layer | Technology |
|-------|------------|
| 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 (75+ migrations) |
| Auth | JWT (python-jose) + bcrypt, refresh token rotation |
| 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) |

---

## Project Structure

```
resolutionflow/
├── backend/
│   ├── app/
│   │   ├── main.py                 # FastAPI entry point
│   │   ├── api/endpoints/          # Route handlers (50+ endpoints)
│   │   ├── core/                   # Config, database, permissions, security
│   │   ├── models/                 # SQLAlchemy models
│   │   ├── schemas/                # Pydantic schemas
│   │   └── services/psa/           # PSA provider abstraction layer
│   ├── alembic/                    # Database migrations
│   ├── scripts/                    # Seed + sync scripts (incl. sync_stripe_plan_ids.py)
│   └── tests/                      # Integration tests (100+)
├── frontend/
│   ├── src/
│   │   ├── components/             # UI components by domain
│   │   ├── pages/                  # Page components
│   │   ├── store/                  # Zustand stores
│   │   └── types/                  # TypeScript interfaces
├── .ai/                            # Dual-agent handoff system (PROJECT_CONTEXT, HANDOFF, etc.)
├── docs/                           # Design docs, plans, ConnectWise reference
├── brand-assets/                   # SVGs, brand guide
├── CLAUDE.md                       # AI assistant project context (Claude Code)
├── AGENTS.md                       # AI assistant project context (Codex; shared protocol with CLAUDE.md)
├── CURRENT-STATE.md                # Detailed feature status
├── DESIGN-SYSTEM.md                # Visual + interaction design system
├── PRODUCT.md                      # Design intent and brand personality
└── CHANGELOG.md                    # Release history
```

> The on-disk repo path is `resolutionflow/`. `patherly` is the legacy internal name — still appears in some Railway service names and the prod DB name. Treat as an alias, not canonical.

---

## Running Tests

```bash
# Backend integration tests
cd backend
pytest --override-ini="addopts="

# Frontend build (stricter than tsc --noEmit)
cd frontend
npm run build
```

---

## Documentation

| Document | Purpose |
|----------|---------|
| [CLAUDE.md](CLAUDE.md) | Project context for Claude Code |
| [AGENTS.md](AGENTS.md) | Project context for Codex (shared protocol with CLAUDE.md) |
| [.ai/PROJECT_CONTEXT.md](.ai/PROJECT_CONTEXT.md) | Stable architectural truth |
| [CURRENT-STATE.md](CURRENT-STATE.md) | Detailed feature status |
| [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) | Development roadmap |
| [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) | Visual + interaction design system (charcoal palette + electric blue accent) |
| [PRODUCT.md](PRODUCT.md) | Design intent, users, brand personality |
| [DEV-ENV.md](DEV-ENV.md) | Development environment setup |
| [CHANGELOG.md](CHANGELOG.md) | Release history |

---

## License

Proprietary. All rights reserved.