​

Web UI

The BioCortex Web UI provides a chat-first interface for running analyses, managing projects, browsing resources, and configuring automation. It uses a Next.js frontend and a FastAPI backend with WebSocket support for streaming.

---

​

Main Areas

---

​

Navigation and Project Linkage

• Sidebar: Icon strip (Chat, Files, Automation, Resources, Settings) + Help + User.
• Project panel: Visible only on the Chat page (and /). On Resources, Automation, Files, and Settings, the project panel is hidden so those pages are focused on their own content.
• Resources link goes to /resources (dedicated Resources page with three tabs and search).

---

​

Running an Analysis

1. Open Chat (and optionally open the Project panel to pick a project).
2. Type a biomedical task in natural language (e.g. “Analyze single-cell RNA-seq data from pbmc.h5ad with clustering and cell type annotation”).
3. The backend:
   • Classifies the task (Strategy Router),
   • Loads or creates an agent with the full tool registry,
   • Runs the appropriate pipeline (ReAct / DAG / MCTS),
   • Streams progress over WebSocket.
4. The UI shows: thinking state (e.g. “Preparing your analysis…”), plan steps, execution status, and final report. Result files appear in the project and in Files.

The same tool registry that backs the Resources page is used for planning and execution — so any tool you see there can be chosen by the Planner and run by the Executor.

---

​

Usage Flow (Step by Step)

---

​

Logic: How the UI and Backend Interact

• Connection — The chat page establishes a WebSocket to /api/v1/ws/chat. All analysis-related messages (user input, plan, steps, report) flow over this socket so the UI can stream updates without polling.
• When you send a message — The frontend (1) appends the user message to the conversation, (2) appends a placeholder assistant message with type thinking and stores its ID, (3) sets “analyzing” to true, (4) sends a JSON message over the WebSocket (e.g. { "type": "message", "content": "...", "project_id": ... }). The backend enqueues the task and runs the strategy/plan/execute pipeline in a worker thread.
• Thinking state — The backend may send { "type": "thinking", "phase": "start"|"update"|"done", "text": "..." }. The frontend updates the placeholder message content. When the first “real” content (e.g. strategy or plan) is sent, the thinking message is cleared or converted to normal text so the user sees a continuous transition from “Preparing…” to the plan.
• Plan and steps — The backend sends plan with a list of steps (name, description, etc.). The UI renders the plan panel and shows step status. As execution proceeds, it sends step_update (or similar) with step index and status (running, done, error, skipped). The frontend updates only that step; when it receives error or done for the whole run, it sets any step still “running” or “retrying” to error or skipped so the panel reflects the final state.
• Report — When synthesis finishes, the backend sends a message with type: "report" and the report content (and optionally report_data with summary, follow-up questions, etc.). The frontend appends this as an assistant message and opens the Result Viewer so the user sees the report with embedded figures and captions.
• Project loading — When you click a project, the frontend calls GET /projects/{id}. If the response includes a conversation, it is mapped to chat messages and the plan/results are restored. If the conversation is empty, the UI still switches to the chat view and shows a single placeholder message so the user can continue. If the request fails (e.g. 404 or network error), the UI shows an in-chat error message and, if possible, still opens the chat with the project title so the user can retry or start a new task.

---

​

Upload and Progress

• Progress bar — When you upload files (from Chat or the Files page), the UI shows upload progress: percentage, bytes transferred (e.g. “2.1 MB / 5.0 MB”), and upload speed (e.g. ”↑ 1.2 MB/s”) when available.
• Indeterminate state — If the server does not return a total size, a pulsing progress bar is shown until the upload completes.
• Cancel — Uploads can be cancelled via the control next to the progress indicator.

---

​

Immediate Feedback (Thinking State)

• As soon as you send a message, the chat shows a short assistant placeholder (e.g. “Preparing your analysis…”). This gives immediate feedback instead of a blank screen while the backend plans and starts execution.
• The placeholder is updated or replaced when the first real content arrives (e.g. strategy, plan steps, or report). If the analysis fails, it is replaced by the error message.

---

​

Simple Questions vs. Analysis Tasks

• Automatic detection — BioCortex distinguishes between simple conversational questions (e.g. “What model are you using?”, “What can you do?”, “Help”) and analysis tasks (e.g. “Analyze my single-cell data with clustering”).
• Simple questions — If the message is a short question about the framework, a greeting, or a help request without attached files or analysis keywords, it is answered directly via the quick-chat LLM. No analysis pipeline is triggered; you get a conversational response immediately.
• Analysis tasks — If the message contains analysis keywords (e.g. “analyze”, “cluster”, “QC”), references data files, or has attachments, the full pipeline is triggered (strategy → plan → execution → report).
• This ensures you don’t accidentally start a long-running analysis when you just want to ask a quick question.

---

​

Plan Confirmation (Integrated with Input)

• When the pipeline generates a plan and requires your confirmation, the confirmation UI appears in the input area (at the bottom of the chat), not as a floating card in the middle of the message list.
• The confirmation card shows:
  • “Yes, proceed with the plan” — Start execution.
  • “No, stop planning” — Cancel the analysis.
  • Text input — Type feedback to modify the plan (e.g. “Add differential expression step”).
• This keeps the chat timeline clean and puts the confirmation where you naturally interact (the input area).

---

​

Projects and Task History

• Project list — The project panel (Chat page) lists your tasks. Clicking a project loads its conversation (messages, plan, results) into the chat view.
• Empty conversation — If a project has no saved messages, the UI still opens the chat view and shows a placeholder message (e.g. “No conversation was saved for this task. You can continue by sending a message below.”) so you can continue in context.
• Errors — If loading a project fails (e.g. network error or project not found), the UI shows an in-chat message with clear guidance (e.g. “Cannot reach the server…” or “This project was not found…”) instead of leaving the screen blank. You can start a new task or retry from the same view.

---

​

Files Page

• Layout — The Files page provides a file manager with tabs for Uploads and Results (and optional grouping). You can switch between list and grid view for easier browsing.
• Upload — A prominent Upload dropdown lets you choose Upload files or Upload folder. A New folder action is available for future organization.
• Empty state — When there are no files, an empty-state card with a short description and Upload files / Upload folder buttons is shown so you can upload without hunting for controls.
• Refresh — A Refresh button reloads the file list from the server.

---

​

Sidebar – Files Tab

• On the Chat page, the project panel includes a Files tab.
• When files exist: it shows a file count, a View all link to the full File Manager (/files), and a compact list of recent files (icons, names, sizes). An Open File Manager button takes you to the Files page.
• When no files exist: it shows a short hint and the same Open File Manager button so you can upload from there.

---

​

Reports and Figure Captions

• Result viewer — After an analysis completes, the report is shown in the Result Viewer (Markdown rendered with embedded images).
• Figure numbering — Every figure in the report is labeled Figure 1, Figure 2, … Figure N in order of appearance, in line with academic (e.g. Nature-style) formatting.
• Caption and explanation — Each figure has:
  • A short subtitle (one line),
  • A brief explanation (one or two sentences) describing what the figure shows and how to interpret it.
• When an LLM is configured, captions and explanations can be generated automatically; otherwise template text is used. The same numbering and captions are used in the downloadable PowerPoint (see Reports and Presentations).
• Download — You can download the report (Markdown) or export to HTML/PDF/Word via the report actions. The PPT can be generated and downloaded from the project’s result actions.
• Analysis status — While the pipeline runs, each step shows a spinner when in progress. When the analysis fails or completes, all running/retrying steps are updated immediately (failed → error icon, pending → skipped) so spinners do not stay on after the run has ended. Step errors are shown with short, readable messages (e.g. gateway timeouts are summarized instead of raw HTML).

---

​

Backend and API

• Backend: FastAPI app (biocortex.web.app); REST + WebSocket.
• WebSocket: WS /api/v1/ws/chat — streaming analysis (messages, plan updates, results).
• REST: Projects, files, results, status, webhooks, cron, GET /api/v1/resources for the Resources page, auth, settings. See API Reference.

---

​

Authentication

Login/register and session handling are provided by the backend (e.g. cookie-based). Frontend calls getMe() to ensure the user is authenticated; unauthenticated users are redirected to login. Per-user agent state and config (e.g. build_config_for_user(username)) are used for analysis and resources.

---

​

Next Steps

• Reports and Presentations — Figure numbering, captions, and PPT generation.
• Resources Page — Databases, Tools, Packages.
• Automation User Guide — Monitors, webhooks, cron.
• Getting Started — How to run the Web UI locally.