Michael Chihlas
029680ab2d
Replaces the legacy flowpilot_engine.escalate_session orchestration with
a single canonical path through HandoffManager. Every escalation now
creates a SessionHandoff row, fans out via the SSE bus, persists
AppNotification rows for the bell icon, dispatches to external channels
(Slack/Teams) via notify(), and emails per-user — regardless of whether
the call entered through /escalate (legacy URL) or /handoff (new URL).
The senior-pickup magic-moment screen now works end-to-end from the
EscalateModal bell-icon path the user just tested.
Backend
- HandoffCreateRequest gains optional target_user_id (the equivalent of
the legacy escalated_to_id field). Self-targeting rejected.
- HandoffManager.create_handoff handles intent='escalate' end-to-end:
sets escalation_reason + escalated_to_id, builds the legacy enhanced
AI escalation_package (Sonnet, lazy-imported from flowpilot_engine,
graceful fallback on failure), and merges handoff metadata into it.
Eager-loads session.steps and session.user via selectinload — required
by both the enhanced-package builder and notify() to avoid
MissingGreenlet on async lazy access.
- HandoffManager.finalize_escalation generates SessionDocumentation,
pushes documentation to PSA, and runs notify() — pre-commit so the
AppNotification rows persist atomically with the handoff.
- HandoffManager.dispatch_escalation_notifications keeps only the
fire-and-forget IO (bus publish, per-user emails) — runs post-commit.
Pulls engineer name via a separate User query rather than relying on
session.user lazy access.
- /handoff endpoint passes target_user_id through and calls
finalize_escalation pre-commit.
- /escalate endpoint is now a thin shim: owner-only session lookup,
HandoffManager.create_handoff(intent='escalate'), finalize_escalation,
commit, dispatch_escalation_notifications, return SessionCloseResponse
built from documentation + psa_result. flowpilot_engine.escalate_session
is no longer called by any endpoint.
- pickup_session accepts both 'requesting_escalation' (legacy in-flight
sessions) and 'escalated' (new canonical) so the migration is seamless
for sessions already in the queue.
- Escalation queue list and sidebar count now match either status.
Frontend
- useFlowPilotSession optimistic update flips status to 'escalated'
instead of 'requesting_escalation' so the page state matches the
unified backend response.
Verified end-to-end live: a fresh /escalate call from the junior produces
status='escalated', a SessionHandoff row, a SessionDocumentation, PSA
push attempted (no_psa for this test session), AND a bell-icon
AppNotification for the team admin with link
/pilot/{session_id}?pickup=true. Backend test suite: 1103 passed.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Troubleshooting Decision Tree - Backend API
FastAPI backend for the Troubleshooting Decision Tree application.
Quick Start
1. Set up Python environment
cd backend
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
pip install -r requirements.txt
2. Start PostgreSQL database
Using Docker:
docker-compose up -d
Or install PostgreSQL locally and create a database:
CREATE DATABASE decision_tree;
3. Configure environment
Copy the example env file and update as needed:
cp .env.example .env
4. Run database migrations
alembic upgrade head
5. Start the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
The API will be available at:
- API: http://localhost:8000
- Docs: http://localhost:8000/api/docs
- ReDoc: http://localhost:8000/api/redoc
API Endpoints
Authentication
POST /api/v1/auth/register- Register new userPOST /api/v1/auth/login- Login (form data)POST /api/v1/auth/login/json- Login (JSON body)POST /api/v1/auth/refresh- Refresh tokenGET /api/v1/auth/me- Get current userPOST /api/v1/auth/logout- Logout
Trees
GET /api/v1/trees- List all treesGET /api/v1/trees/categories- List categoriesGET /api/v1/trees/search?q=query- Search treesGET /api/v1/trees/{id}- Get specific treePOST /api/v1/trees- Create tree (engineer/admin)PUT /api/v1/trees/{id}- Update tree (engineer/admin)DELETE /api/v1/trees/{id}- Delete tree (admin)
Sessions
GET /api/v1/sessions- List user's sessionsGET /api/v1/sessions/{id}- Get specific sessionPOST /api/v1/sessions- Start new sessionPUT /api/v1/sessions/{id}- Update sessionPOST /api/v1/sessions/{id}/complete- Complete sessionPOST /api/v1/sessions/{id}/export- Export session
Development
Create new migration
alembic revision --autogenerate -m "description"
Run migrations
alembic upgrade head
Rollback migration
alembic downgrade -1
Project Structure
backend/
├── alembic/ # Database migrations
│ └── versions/
├── app/
│ ├── api/
│ │ ├── endpoints/ # API route handlers
│ │ ├── deps.py # Dependencies (auth, etc.)
│ │ └── router.py # Main router
│ ├── core/
│ │ ├── config.py # Settings
│ │ ├── database.py # DB connection
│ │ └── security.py # JWT, password hashing
│ ├── models/ # SQLAlchemy models
│ ├── schemas/ # Pydantic schemas
│ └── main.py # FastAPI app
├── tests/
├── alembic.ini
├── docker-compose.yml
├── requirements.txt
└── README.md