Master Pages: Backend Handoff | Frontend Handoff | Backend Colab Entry | Frontend Colab Entry

Scout Fleet — Frontend Handoff

Date: 2026-03-25 From: Backend (Scout Fleet API complete) To: Frontend Team Status: Ready for implementation

What's Built (Backend)

The Scout Fleet API is live at :4812. Every screen described below has a working API endpoint. The frontend team needs to build the UX that calls these endpoints.

API Base: http://localhost:4812/api/v1 Auth: Pass X-User-Id and X-Tenant-Id headers (IAM middleware will replace this with real auth tokens in production) WebSocket: ws://localhost:4812/api/v1/scouts/ws

Screens To Build

Screen 1: My Scouts (List View)

URL: /scouts API: GET /api/v1/scouts

Shows all user's Scouts with status, last run, next run, finding count. Header shows count (8/25).

Components needed: - Scout card grid/list (name, status badge, process type icon, last run time, finding count, gateway usage) - Status badges: ● Active (green), ⏸ Paused (amber), ⚠ Failed (red), ⛔ Killed (red) - Empty state with onboarding (see Screen 8) - "Scouts For You" section at bottom (see Screen 7) - Count badge: "8/25 Scouts"

Actions per card: - Click → Scout Detail (Screen 3) - [Pause] → POST /api/v1/scouts/{id}/pause - [Run Now] → POST /api/v1/scouts/{id}/run - [Edit] → Scout Builder (Screen 2) pre-filled

Real-time: WebSocket scout.status.changed events update card status live

Screen 2: Scout Builder (Create/Edit)

URL: /scouts/new or /scouts/{id}/edit API: POST /api/v1/scouts (create) or PUT /api/v1/scouts/{id} (update)

Visual builder with dropdowns — no code, no YAML.

Form fields:

Field Type API Field Options
Name Text input (60 char max) config.name Free text
Input Source Dropdown config.input_source.source_type entity, domain, region, theme, feed, media, scout
Entities Multi-select (searchable) config.input_source.entities From KB entity list
Domains Multi-select config.input_source.domains telecom, biotech, fintech, etc.
Focus Text input config.input_source.focus Free text (optional)
Process Type Dropdown config.process_type track, summarize, compare, challenge, connect, score, research, synthesize, process
Schedule Dropdown config.schedule "every 30 minutes", "every hour", "every 4 hours", "daily", "weekly", "on-demand"
Mode Radio config.mode local, augmented
Sensitivity Dropdown config.sensitivity any_change, significant_only
Challenge Thesis Text input (if process=challenge) config.challenge_thesis Free text
Score Criteria Tag input (if process=score) config.score_criteria Free text tags
Output Destinations Multi-select with config config.outputs[] See output destinations below

Output destination config (each destination may need additional fields):

Destination Additional Config Fields
Dashboard None
Chat None
Email email_address
Discord webhook_url
Slack webhook_url
Dropbox folder_path (needs OAuth connection first)
Webhook url, headers (optional)
File Export format (pdf/csv/json)
Another Scout scout_id (dropdown of user's other Scouts)

Connected accounts: Show which output destinations are connected. If not connected, show "Connect" button that opens OAuth flow. API for connections: GET /api/v1/outputs/connections, POST /api/v1/outputs/connections

Screen 3: Scout Detail

URL: /scouts/{id} API: GET /api/v1/scouts/{id}

Full detail view with tabs:

Header: Name, status badge, mode badge, created date, next run countdown Action buttons: [Run Now] [Pause/Resume] [Edit] [Clone] [Delete]

Tab: Output (default) - Latest run output: GET /api/v1/scouts/{id}/runs/latest - Full text output with formatting - Feedback buttons: 👍 👎 "This is wrong" - API: POST /api/v1/scouts/{id}/runs/{run_id}/feedback

Tab: Run History - List of runs: GET /api/v1/scouts/{id}/runs - Each row: timestamp, status, duration, findings count, gateway calls - Click row → expand to see full output

Tab: Analytics - GET /api/v1/scouts/{id}/analytics - Run count, findings count, engagement rate, time saved estimate - Sparkline trend charts (findings per week)

Tab: Versions - GET /api/v1/scouts/{id}/versions - Config version history - [Rollback] button: POST /api/v1/scouts/{id}/rollback/{version}

Screen 4: Pipeline Builder

URL: /scouts/pipelines API: GET /api/v1/pipelines, POST /api/v1/pipelines

Visual drag-and-drop canvas where users connect Scouts.

Components: - Canvas with Scout nodes (each node = one Scout card) - Drag connections between nodes (output → input) - Connection lines with arrow indicators - IF/THEN/ELSE conditional nodes (Phase 2) - [Run Pipeline] button: POST /api/v1/pipelines/{id}/run - Desktop only (not mobile)

Node data: Each node shows Scout name, status, process type icon Connection data: POST /api/v1/pipelines/{id}/connect with {from_scout_id, to_scout_id}

Screen 5: Template Library

URL: /scouts/templates API: GET /api/v1/templates

Browse and use Scout templates.

Layout: - Category tabs: Trending, For VCs, For Corporates, For Accelerators, For Government - Template cards: name, description, usage count, avg rating, category badge - [Use Template] → POST /api/v1/templates/{id}/use → opens Scout Builder pre-filled - [Preview] → shows what the Scout would produce - Star rating (1-5): POST /api/v1/templates/{id}/rate

Publish flow (from Scout Detail): - [Publish to Library] → modal: category dropdown, description field - POST /api/v1/scouts/{id}/publish

Screen 6: Clone Scout

URL: Modal from Scout Detail API: POST /api/v1/scouts/{id}/clone

Components: - Source Scout name (read-only) - New name field - Override fields: input source entities/domains (pre-filled from source) - [Create Clone] button

Screen 7: Scouts For You

API: GET /api/v1/recommendations

Section at bottom of My Scouts list.

Card layout: - Title, description, confidence source ("Based on your research patterns", "Popular with VCs") - [Activate] → POST /api/v1/recommendations/{id}/activate → creates Scout - [Preview] → POST /api/v1/recommendations/{id}/preview → shows sample output - [Dismiss] → POST /api/v1/recommendations/{id}/dismiss

Screen 8: Onboarding (Empty State)

Shown when user has 0 Scouts.

Components: - Welcome illustration - "Create Your First Scout" CTA button - Quick Start cards: "Track an Entity", "Weekly Briefing", "Research a Topic" - Each quick start pre-fills Scout Builder with that template

Screen 9: Usage & Billing

URL: /scouts/usage API: GET /api/v1/usage, GET /api/v1/billing/usage

Components: - Quota bars: Scouts (8/25), Gateway calls today (120/200), FMIE files (3/50) - Usage history chart (daily/weekly/monthly) - Per-scout cost breakdown table - Upgrade prompt if approaching limits

Screen 10: Notification Preferences

URL: /settings/notifications (or modal) API: GET /api/v1/notifications/preferences, PUT /api/v1/notifications/preferences

Form fields: - Quiet hours: start time, end time, timezone dropdown - Digest mode: toggle - Digest interval: dropdown (hourly, every 4 hours, daily) - Priority filter: dropdown (all, high only, critical only) - Per-channel mute toggles

Screen 11: Global Admin Dashboard

URL: /admin/scouts API: GET /api/v1/admin/fleet, GET /api/v1/admin/fleet/scouts

For operator only (admin role in IAM).

Components: - Fleet stat cards: total scouts, active, paused, failed, killed, users, runs today, gateway today - Alert/warning/intelligence panels (RED/AMBER/BLUE) - Filterable Scout table (all users, all tenants) - Per-user view: GET /api/v1/admin/fleet/users - Per-tenant view: GET /api/v1/admin/fleet/tenants - Action buttons: [Pause] [Kill] [Resume] per scout - Admin WebSocket: ws://localhost:4812/api/v1/admin/fleet/ws

Screen 12: Connected Accounts

URL: /settings/connections API: GET /api/v1/outputs/connections

Components: - List of output destinations with connection status - [Connect] button per destination (initiates OAuth) - [Test Connection] button: POST /api/v1/outputs/connections/{id}/test - [Disconnect] button: DELETE /api/v1/outputs/connections/{id}

Mobile Considerations

Screen Mobile Support
My Scouts (list) ✅ Full — primary consumption surface
Scout Detail ✅ Full — output viewing
Scout Builder ✅ Simplified — dropdowns work
Pipeline Builder ❌ Desktop only — drag-and-drop
Template Library ✅ Full
Notifications ✅ Push notifications via mobile
Admin Dashboard ✅ Read-only summary

Design Notes