# UX Audit: PMF Readiness for First Market Offer

**Date:** 2026-04-01
**Epic:** Gitea #100
**Timeline:** 8 weeks to first market offer (~2026-05-27)

## Context

Comprehensive UX audit evaluating readiness for product-market fit. Full-stack Apache Camel observability platform competing with Datadog, Grafana+Tempo, Dynatrace. Self-hosted first, SaaS later.

**Three target personas (all equally important):**
- Integration Developers -- debug message flows, trace exchanges, inspect payloads/errors
- DevOps/Platform Engineers -- manage deployments, agent health, route control, config push
- Engineering Managers / Tech Leads -- dashboards, SLA compliance, error trends

**Competitive positioning:** "General APM tools don't understand Camel. We do."

## What's Working Well

- Process diagram visualization -- killer differentiator, no APM tool shows Camel routes this way
- Three-tab navigation (Exchanges/Dashboard/Runtime) maps cleanly to personas
- Command palette (Ctrl+K) with categorized search is polished
- Dashboard 3-level drill-down with KPIs, treemaps, punchcard heatmaps -- competitive-grade
- Dark mode is clean and well-implemented
- Design system gives visual consistency; amber/brown brand is distinctive
- Route control bar (Start/Stop/Suspend/Resume/Replay) -- unique differentiator
- Live auto-refresh with LIVE indicator
- Correlation chain navigation

## Issues Created

### P0 -- Ship Blockers
- #101 Onboarding & empty state experience (spec posted)
- #102 Alerting & notification system (spec posted)
- #103 Shareable links with filter state (spec posted)

### P1 -- Must Have
- #104 Log search experience (spec posted)
- #105 Exchange table readability (spec posted)
- #106 Latency outlier investigation path (spec posted)

### P2 -- Should Have
- #107 Data export CSV/JSON (spec posted)
- #108 Sidebar consolidation & tab-awareness (spec posted)
- #109 Dashboard L3 diagram readability (spec posted)
- #110 Time/locale formatting consistency (spec posted)
- #111 Pagination & deep result access (spec posted)

### P3 -- Polish
- #112 Admin page context separation (spec posted)
- #113 Runtime suspended routes context (spec posted)
- #114 App Config detail full page (spec posted)
- #115 Comparative & historical analysis (spec posted)

## Recommended 8-Week Execution Order

| Weeks | Issues | Focus |
|-------|--------|-------|
| 1-2 | #103, #105, #110 | Quick wins: shareable links, table readability, formatting |
| 3-4 | #101, #111 | First-run experience, pagination |
| 5-6 | #102 | Alerting (the big sticky feature) |
| 7-8 | #104, #106 | Depth: log search, latency investigation |

## Design Specs

Full design specifications are posted as comments on each Gitea issue. Key architectural decisions:

### #101 Onboarding
- `useOnboardingState()` hook derives phase from existing `useAgents()` + `useRouteCatalog()` polling
- Phases: welcome -> connected -> receiving -> complete -> dismissed
- Framework-specific snippets (Spring Boot/Quarkus/Standalone x Maven/Gradle)
- Bootstrap token via new `GET /api/v1/admin/bootstrap-token` (ADMIN only)
- Per-page empty states using DS `EmptyState` component

### #102 Alerting
- PostgreSQL tables: alert_channels, alert_rules, alert_history, alert_rule_state
- 7 built-in alert types querying ClickHouse MVs and agent registry
- Evaluation engine: Spring @Scheduled, 10s loop, hysteresis, cooldown
- 3 notification channels: webhook, email (SMTP), Slack
- Bell icon in TopBar with firing count badge
- New "Alerting" admin tab with Rules/Channels/History sub-tabs

### #103 Shareable Links
- URL as canonical source of truth, React state is derived mirror
- `UrlFilterSyncProvider` wraps existing `GlobalFilterProvider` (no DS changes)
- Filter changes = replaceState, navigation = pushState
- Copy Link button with Ctrl+Shift+C shortcut
- 9-step incremental rollout

### #104 Log Search
- New `GET /api/v1/logs/search` endpoint with cursor pagination and level counts
- 4th tab: Logs, with search bar, level filter toggles, virtual-scrolled results
- Search syntax: free text + field:value (level, app, logger, exchange, mdc.*)
- Live tail via adaptive polling (2-5s)
- Bidirectional exchange correlation