researchx/frontend/README.md

ResearchX Frontend

TL;DR — This is the ResearchX web interface: ask a question, choose a research method, approve the plan, watch the live trace, read the cited report. The prototype runs entirely on scripted sample data — no API keys, no backend, no network — so the full product journey is tryable today.

• What — A Next.js app (ask, choose, run, report, library, settings) rendering mock data through one typed client interface.
• Why — The journey is checkable end-to-end before live inference exists.
• Action — no action — FYI. Developers: Quickstart below (Node 20+, pnpm).
• Details — Root README.md: backend engine, live mode, architecture.

The prototype frontend for ResearchX — methodology-driven deep research with a trust loop. This milestone (v0.1) runs entirely on mock data: no API keys, no env vars, no network calls beyond static assets.

Quickstart

Prerequisites: Node 20+ and pnpm (any recent version; the repo was built with pnpm 12).

cd frontend
pnpm install
pnpm dev

Open http://localhost:3000 — you'll land on /ask, inside the app shell (left sidebar for navigation, top bar with search and your avatar).

The happy path:

1. Type a question (context is optional) → Research this
2. Pick a methodology on /choose — Deep Report is the recommended default; open Advanced on any card to see its 12 dials
3. Start research → /run/[id]: review the plan (sub-questions, source universe, outline), Approve plan, and watch the scripted live trace stream in — Pause/Resume or Cancel at any time
4. When the run completes → Read the report → /run/[id]/report: the Reading Room renders the report with page-anchored citations — hover or focus any [n] marker to see the exact quoted passage — plus the citation ledger and Export Markdown/JSON buttons that download real files with citations as real links

The shell adds zero required clicks to that path. Everything else it hosts is wayfinding and accumulated research:

• Open questions (/ask, below the form) — follow-up suggestions derived from unanswered questions of your past runs; one click loads one into the question box for editing (never auto-starts).
• Refine question (/ask, beside the box) — an opt-in back-and-forth: a few clarifying questions, then a composed refined question with suggested context. Use it, or keep your original. Scripted in the prototype — model-driven refine lands with v0.2.
• Library (/library) — every report you've generated, filed into auto-categorized folders; sort by recency or title; open any card to re-enter its Reading Room. The Connections panel draws the links between reports — shared sources (⇄) and adjacent topics (→). The project graph and task inbox remain v2 previews.
• Settings (/settings) — API-key status (masked, never raw), the local directory reports are stored in, the default methodology and the 12 dials it resolves to, appearance, and about/version.
• ⌘K (top bar) — jump to any screen or stored report. Navigation only; full search arrives with the v0.2 engine.
• Avatar (top bar, right) — local single-user profile, links to Settings and About.

Scripts

Script	What it does
pnpm dev	Start the Next.js dev server on port 3000
pnpm build	Production build
pnpm start	Serve the production build
pnpm lint	ESLint (flat config, eslint-config-next)
pnpm typecheck	tsc --noEmit (TypeScript strict)
pnpm test	Vitest run (jsdom + Testing Library)
pnpm test:watch	Vitest in watch mode

Architecture notes

• All data access goes through the typed ApiClient interface (src/lib/api/client.ts) — components import the api singleton and never touch MockApiClient directly. v0.2 phase 3 swaps the binding to the OpenAPI-generated backend client with no component rewrites.
• The mock layer lives in src/lib/api/mock/: fixture data for all 8 locked methodologies, a scripted Deep Report run (trace events, report with [^passageId] citation markers, citation ledger), the stored-reports library with folders and cross-report connections, adapter connection status, settings, and the local user profile.
• The app shell (sidebar + top bar) lives in the root layout (src/app/layout.tsx); every screen renders inside it.
• Design tokens (editorial type scale, warm paper palette, spacing) are defined as Tailwind v4 @theme tokens in src/app/globals.css.
• Question + context survive the /ask → /choose navigation via a small module-level store (src/lib/ask-store.ts).

Project layout

src/
  app/            App Router routes (ask, choose, run/[id], run/[id]/report,
                  library, settings) — all inside the shell layout
  components/     UI components (shell chrome, screens, tests co-located)
  lib/            Domain types, ApiClient boundary, mock data, stores
  test/           Test harness setup

Prototype scope note: ETAs, cost estimates, the scripted run, the stored reports, connection edges, and adapter statuses are realistic fixture data — not live research. The trace stream replays a deterministic Deep Report run with pause/resume/cancel controls; the Reading Room's report, ledger, and exports are generated from the same fixture. API-key entry, live adapter probing, and full search land with the v0.2 backend.