chihlasm/resolutionflow
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
feat/network-map-builder-prod
resolutionflow/CURRENT-STATE.md
chihlasm f54d7ecd78 docs: update current state after Phase 4 merge
2026-04-12 04:35:30 +00:00

12 KiB
Raw Permalink Blame History

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 12, 2026

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

What's Complete

Core Platform

  • FastAPI project structure with 35+ API endpoints
  • PostgreSQL database with Docker, 75+ 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 — Flat, high-contrast dark theme (Sentry/PostHog-inspired), charcoal palette with sidebar-darkest approach
  • 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

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)

Tenant Isolation (Phases 1-4 Complete)

  • PostgreSQL RLS enabled across tenant-scoped tables in phased rollout
  • account_id propagation completed across core content, sessions, analytics, notifications, shares, and remaining Phase 4 tables
  • Global platform tables correctly excluded from tenant RLS where they have no account_id (script_categories, platform_steps, template_trees)
  • Runtime bootstrap paths updated to use BYPASSRLS/admin sessions where needed (auth/user mutations, startup service account, background jobs, seed scripts)
  • Preview Railway backend and frontend deployments green for PR 136 after the Phase 4 fixes

Copilot-First Dashboard (March 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)
  • Landing page copy rewrite: "Resolve tickets faster. Notes write themselves."
  • Spring bounce hover animation on dashboard cards
  • Charcoal color palette: sidebar #10121a, page #1a1c23, cards #22252e

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

# Start PostgreSQL (Docker Compose)
docker compose up -d

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

# Frontend (from frontend/)
npm run dev

URLs

Run Tests

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
Reference in New Issue View Git Blame Copy Permalink