resolutionflow/CURRENT-STATE.md

# Current State

> **Purpose:** Quick-reference file showing exactly where the project stands.
> **For Claude Code:** Read this first to understand what's done and what's next.
> **Last Updated:** April 4, 2026

---

## Active Phase: Go-to-Market Validation (Pre-PMF)

---

## What's Complete

### Core Platform
- FastAPI project structure with 55+ API endpoints
- PostgreSQL database with Docker, 100+ Alembic migrations
- User authentication (JWT, register, login, refresh, logout, invite codes)
- Refresh token rotation with JTI-based revocation
- Trees CRUD with full-text search (FTS index)
- Sessions tracking with decisions, outcomes, and variables
- Export API (Markdown, Text, HTML)
- Role-based access control (super_admin, team_admin, engineer, viewer)
- Production-ready logging with correlation IDs
- 100+ integration tests
- Rate limiting on auth endpoints (disabled in DEBUG)
- Audit log table with JSONB details
- Soft delete for trees with cascade cleanup

### Frontend Core
- React 19 + Vite + TypeScript + Tailwind CSS v4 (`@tailwindcss/vite`)
- **Charcoal Design System v6** — Flat, high-contrast dark theme (Sentry/PostHog-inspired), charcoal palette; accent color is electric blue (#60a5fa), replacing ember orange
- **Brand fonts:** Bricolage Grotesque (headings), IBM Plex Sans (body), JetBrains Mono (code)
- Authentication UI (login, register, email verification)
- Tree library/browsing page with grid/list/table views
- Tree navigation interface (session player)
- Session management with history and detail pages
- **Tree Editor** — Form-based with visual preview, Zustand + immer + zundo (undo/redo)
- **Markdown rendering** in session player and node editor
- **Tree Organization** — Categories, tags (autocomplete), user folders (3-level hierarchy), filters
- **RBAC & Permissions** — `usePermissions` hook, ProtectedRoute with role guards
- **Session Scratchpad** — Floating overlay (Ctrl+/), auto-save, markdown preview
- **Admin Panel** — 8 pages (dashboard, users, invite codes, audit logs, plan limits, feature flags, settings, categories)
- **Session Quick Wins** — Timer, keyboard hints, repeat last, auto-recovery, copy step, delete tree
- **Session Outcomes** — Outcome modal on completion, step timing tracking
- **Session Sharing** — Share links, public/account views, MySharesPage
- **Procedural Editor UX** — Section headers, collapsible advanced fields, URL intake, tag input
- **Type-aware Routing** — Centralized `getTreeNavigatePath`/`getTreeEditorPath` helpers
- **Account Management** — Profile settings, delete/leave/transfer, chat retention
- **PostHog Analytics** — Event tracking, user identification, autocapture

### FlowPilot AI System (Phases 1-3 Complete)

**Phase 1 — AI Session Engine:**
- FlowPilotEngine with multi-step guided troubleshooting
- AI copilot panel + standalone assistant chat with RAG
- Confidence-tiered model routing via `settings.get_model_for_action()`
- Intake form with ticket/client fields, session pause/resume
- AI-generated ticket summaries, outcome tracking

**Phase 2 — PSA Integration & Escalation:**
- ConnectWise PSA integration (ticket linking, note posting, member mapping)
- PSA documentation auto-push with retry scheduler
- Session pause/resume, mid-session ticket linking
- Escalation handoff workflow with LLM-enhanced briefing package
- Escalation pickup flow for senior engineers
- PSA settings UI on IntegrationsPage
- In-session script generator

**Phase 3 — Knowledge Flywheel:**
- AI session analysis → automatic flow proposal generation
- FlowProposal model with review queue (approve, edit & publish, dismiss, reject)
- Knowledge gap detection (weak options, high escalation domains)
- FlowPilot analytics dashboard (metrics, confidence tiers, PSA stats, gaps)
- APScheduler batch analysis job with `max_instances=1`
- Auto-reinforcement for sessions matching existing flows

### Phase 4 — Enterprise & Growth Features (All Slices Complete)

**Slice 1 — Public Templates Gallery:**
- Public API endpoints (no auth): gallery listing, flow/script detail, categories, search
- `is_gallery_featured` and `gallery_sort_order` columns on trees and script_templates
- IP-based rate limiting (30/min), tree structure truncated to 3 levels (signup wall)
- Public `/templates` page with hero, search, category filters, responsive card grid
- Detail modal with tree preview or parameter list + signup CTA
- Admin gallery curation page (feature toggle, sort order)
- 25 backend tests

**Slice 2 — Notification System:**
- NotificationConfig, NotificationLog, Notification models + migration
- Multi-channel delivery: in-app, email (Resend), Slack webhooks, Teams webhooks
- Notification service with event routing and fire-and-forget delivery
- APScheduler retry job with exponential backoff (30s, 2m, 10m, max 3 retries)
- 9 API endpoints (config CRUD + in-app notification management)
- Wired into escalation, proposal approval, and knowledge flywheel events
- Frontend: NotificationsPanel (bell icon + dropdown), NotificationSettings UI

**Slice 3 — Session Export (Polish):**
- 5-format export already existed (markdown, text, HTML, PSA, PDF via WeasyPrint)
- Added "Generated with ResolutionFlow" branding footer to all 5 formats
- Fixed PDF template conditional that was hiding branding
- Added spinner for PDF generation loading state

**Slice 4 — Mobile/Responsive:**
- Responsive audit pass across 11 FlowPilot and analytics components
- FlowPilotSession: collapsible mobile sidebar, single-column layout on mobile
- Action bars: full-width stacked buttons on mobile, 44px touch targets
- Modals: full-width slide-up pattern on mobile
- ReviewQueuePage: stacked panels on mobile
- Analytics: single-column chart stack on mobile

**Slice 5 — Enterprise Readiness:**
- Custom branding: logo URL, primary accent color, company name (owner-only)
- CSS variable overrides applied in app shell for accent color
- Branding settings page under Account Settings
- Autotask PSA and Halo PSA stub providers (Coming Soon badges in UI)
- SSO/SAML groundwork: sso_enabled, sso_provider, sso_config columns on Account
- SSO stub service with interface methods
- "Contact us to enable SSO" section in Account Settings

### Phase 5 — Analytics Enhancement (Complete)

- Tabbed analytics page: Overview, Coverage, Flow Quality, PSA
- Coverage heatmap: domain grid with color-coded cells (resolution/escalation/guided rates, flow count)
- Domain-to-flow mapping via category cross-reference
- Flow quality scoring endpoint: quality_score = (success_rate * 0.5) + (guided_rate * 0.3) + (recency * 0.2)
- Flow quality table: sortable, top performers (emerald), needs attention (rose), mini score bars
- Flow usage tracking: usage_count, success_rate, last_matched_at wired into session matching + resolution
- PSA activity logging: psa_activity_logs table, wired into documentation push service
- Enhanced PSA metrics: time entries, hours logged, push success funnel, daily trend chart
- 13 new backend tests for coverage and flow quality endpoints

### Conversational Branching (Complete)

- SessionBranch, ForkPoint, SessionHandoff, SessionResolutionOutput models + migration (4 tables, 13 columns)
- BranchManager service, BranchAwarePromptBuilder, HandoffManager service with integration tests
- Branch API endpoints: `session_branches.py`, `session_handoffs.py`, `session_resolutions.py`
- Integrated into `unified_chat_service.py` and AI session step creation
- Frontend: BranchNode, ForkCard, BranchMap, BranchRevivalCard, BranchTransitionBar, HandoffModal, ResolutionOutputPanel components
- Wired into FlowPilotSession and `useFlowPilotSession` hook

### Script Library Enhancements (Complete)

- ParameterizeAndSavePanel replaces SaveToLibraryDialog — accepts `script_body` and `parameters_schema` in save flow
- "New from Script" button on ScriptLibraryPage for one-click script creation from template
- Default tab is "All Scripts" (previously filtered to owned scripts)
- Ownership filter state preserved across category and search changes
- Backend: `save-to-library` endpoint accepts `script_body` + `parameters_schema`

### AI Vision Support (Complete)

- Image uploads (paste/drag-drop) wired into AI assistant chat via `upload_ids`
- Server-side image resize before sending to Claude (Pillow, 1568px max, PNG→JPEG)
- `storage_service.resize_image_for_vision()` handles vision pipeline
- Images are NOT stored in conversation history (text-only history)

### Mid-Session Status Updates (Complete)

- AI assistant can generate `status_update` steps (step_type added to CHECK constraint)
- Status update generation wired into `unified_chat_service.py`
- Frontend renders status update cards in session view

### Search & Recall + Evidence-Rich Sessions (Complete)

**Evidence:**
- Railway Object Storage (S3-compatible) integration via boto3
- file_uploads model with upload/download/list/delete API endpoints
- RichTextInput component: clipboard paste (Ctrl+V) and drag-and-drop for images
- Wired into FlowPilot intake, free-text responses, and escalation modal
- Evidence included in all 5 export formats (markdown, text, HTML, PSA, PDF)
- 15 backend tests for upload endpoints

**Search:**
- Structured filters on AI sessions: problem_domain, matched_flow, confidence_tier, ticket_id, date range
- Filter bar UI on Session History page (AI Sessions tab)
- PostgreSQL full-text search via generated tsvector column + GIN index on ai_sessions
- Command Palette extended with AI session search results
- Voyage AI semantic embeddings on ai_session_embeddings table (pgvector cosine similarity)
- Similar sessions endpoint: GET /ai-sessions/{id}/similar
- Similar Sessions sidebar component in FlowPilot session view

### Security Hardening (Phases A-D Complete)
- Registration role hardcoded to `engineer`
- HTML export XSS fix (html.escape)
- Secret key validator (rejects default when DEBUG=False)
- Role CHECK constraint on users table
- Tree access check on session start
- Centralized permissions in `permissions.py`
- `is_active` field on User model, enforced in auth
- Admin user management endpoints (6 endpoints)
- Password complexity validation (uppercase, lowercase, digit, min 10 chars)
- Soft delete cascade cleanup (folder/tag junctions)
- SQL wildcard escaping in tag search
- PSA credentials encrypted at rest (Fernet)

### Copilot-First Dashboard (March–April 2026)

- Redesigned dashboard as FlowPilot copilot launchpad (ChatGPT-style input)
- Chat-style input with paste images, drag-drop files, attach button, paste logs
- Suggestion chips for common troubleshooting scenarios
- Simplified sidebar: icon rail with Home, History, Flows, Scripts, Data sections
- Amber "New Session" button in sidebar
- Unified Command Palette (Cmd+K) — merged QuickLaunch into omnibar
- "Solutions Library" rename (from "Step Library") site-wide
- Maintenance flows hidden from UI for pilot (backend still supports them)
- Charcoal color palette: sidebar `#0e1016`, page `#16181f`, cards `#1e2028`
- **Landing page redesign** — scroll-driven reveal animations, live chat animation, FAQ section, improved trust signals; copy: "Resolve tickets faster. Notes write themselves."
- **Session History redesign** — tabbed layout with Load More pagination
- **Edit Procedure page** — layout and color system overhaul
- **TaskLane UX** improvements in assistant chat; persistence across page reload
- TaskLane answers persist in sessionStorage; correct behavior on all three chat paths (send, prefill, resume)
- **Action bar consolidation** — Deduplicated actions across FlowPilot/Cockpit headers and chat toolbars; chat toolbar now only has input tools (Attach, Paste Logs, Tasks)
- **ViewToggle redesigned** as persistent tab bar with bottom-border active indicator and ARIA attributes (FlowPilot/Cockpit switcher)
- **Standardized action naming** across all session pages: Resolve (emerald), Update (blue), Close (rose), Pause (muted)
- **ConcludeSessionModal copy refresh** — Forward-facing action verbs, "Close & Generate" CTA, consistent outcome labels
- Deleted unused FlowPilotActionBar component (227 lines dead code)

### Maintenance Flows (Hidden from UI)

- Batch session launch, saved target lists
- APScheduler scheduling with croniter + pytz
- Backend fully functional; removed from sidebar, create dropdown, and filter tabs for GTM pilot

### Survey System
- Public survey page, admin invite tracking
- Response viewer with CSV export
- Email-to-self, thank-you page
- Admin read/unread/archive/delete management

### Documentation
- CLAUDE.md (comprehensive project context)
- UI-DESIGN-SYSTEM.md, REBRAND-IMPLEMENTATION-GUIDE.md
- ConnectWise API reference docs in `docs/connectwise/`
- Feature specifications through Phase 4
- Phase implementation plans in `docs/plans/`

---

## What's In Progress

- **GTM Validation:** Shadow & Ship — founder uses product for 2 weeks, then hands logins to 5 colleagues
- **Solutions Library spec:** Written at `docs/plans/2026-03-23-solutions-library-design.md`, implementation deferred to post-pilot

---

## What's Next (Priority Order)

### Pilot Phase (Weeks 1-2)

- Founder dogfooding: use ResolutionFlow for real MSP tickets daily
- Collect feedback on copilot-first experience
- Fix issues discovered during real usage

### Post-Pilot (Weeks 3-4)

- Solutions Library implementation (saved resolutions + RAG + dedup + confidence scoring)
- Landing page design polish based on pilot feedback
- Dedicated Insights dashboard (strategic metrics for team leads)

### Later (Phase 6+)

- Full Autotask PSA implementation
- Full Halo PSA implementation
- Full SSO/SAML implementation (SAML + OIDC flows)
- PowerShell automation framework
- White-label deployment
- Marketplace for community flow templates
- Native mobile app (React Native or PWA)

---

## Environment Quick Reference

### Start Development
```bash
# Start PostgreSQL (Docker — container name resolutionflow_postgres, port 5433, DB resolutionflow)
docker start resolutionflow_postgres

# Backend (from backend/)
source venv/bin/activate
uvicorn app.main:app --reload

# Frontend (from frontend/, requires Node 20)
npm run dev
```

### URLs
- Frontend: http://46.202.92.250:5173 (or https via Traefik reverse proxy)
- Backend API: http://46.202.92.250:8000
- API Docs: http://46.202.92.250:8000/api/docs
- Dev env runs on Hostinger VPS (46.202.92.250) with Traefik + HTTPS; see [DEV-ENV.md](DEV-ENV.md)

### Run Tests
```bash
cd backend && pytest --override-ini="addopts="
```

---

## Blockers / Known Issues

| Issue | Workaround | Status |
|-------|------------|--------|
| `analysis_status` has no CheckConstraint | Valid values documented in code comments | Low priority |
| Review queue/analytics pages have no frontend role gate | Backend 403 protects data; UX could show message | Low priority |
| Review queue capped at 50 with no pagination UI | Filters can narrow results | Low priority |