Review Studio Overview
Relevant source files
The following files were used as context for generating this wiki page:
Review Studio is the local web interface for marginalia, a tool that monitors GitLab merge requests (MRs) and executes automated code reviews using Claude Code. The studio serves as a "reading desk" where developers review machine-generated reports, manage pending comments, and triage feedback on their own merge requests. It operates locally at http://localhost:4477 and interacts with a local server that handles file system operations and GitLab API communication.
Sources: README.md:144-150, PRODUCT.md:17-21, DESIGN.md:131-135
System Architecture
The studio follows a client-server model where the frontend is a React application and the backend is a Node.js server. The server acts as a thin layer over review files, a status.json file, and the GitLab API.
The diagram shows the data flow between the React frontend, the local Node.js server, and external services.
Sources: studio/public/openapi.yaml:4-10, studio/src/lib/api.ts:133-150, README.md:162-165
Core Features and Components
The studio interface focuses on high density and technical clarity. It organizes content into a Home queue, sidebars for history, and a detailed Review Reader for specific MRs.
Navigation and Layout
- Home View: Lists reviews grouped by state (e.g., "Needs your first review", "Returned to you", "Comments on your merge requests").
- Review Reader: A dedicated view for reading a single review, featuring a guided tour, diff pane, and per-stop chat.
- Tab Strip: Manages open reviews as browser-like tabs with unread indicators and status icons.
- Sidebar: Provides a persistent list of all reviews, available only when a specific review is open.
Sources: README.md:151-158, studio/src/App.tsx:160-185, DESIGN.md:214-225
Key Technical Components
| Component | Description | Source File |
|---|---|---|
App.tsx | Main entry point managing routing, global state, and keyboard shortcuts. | studio/src/App.tsx |
ReviewReader.tsx | Orchestrates the display of markdown content, overview, and guided tours. | studio/src/components/ReviewReader.tsx |
api.ts | Provides hooks (useReviews, useReview) and functions for GitLab interaction. | studio/src/lib/api.ts |
ReviewOverview | Displays "before" and "after" summaries of the change. | studio/src/components/ReviewReader.tsx:77 |
ConfirmSubmit | A modal for reviewing and publishing draft notes to GitLab. | studio/src/components/ConfirmSubmit.tsx |
Sources: studio/src/App.tsx:135-230, studio/src/components/ReviewReader.tsx:32-108
Data Models and State
The studio relies on several key data structures to synchronize the local file state with GitLab's remote state.
Review Item Schema
The ReviewItem represents the metadata for a single review stored on disk.
| Field | Type | Description |
|---|---|---|
slug | string | Unique identifier (filename without extension). |
verdict | Verdict | APPROVE, REQUEST_CHANGES, or OTHER. |
critical | number | Count of critical findings. |
important | number | Count of important findings. |
stale | boolean | True if the MR head SHA has changed since the review. |
tracked | boolean | True if a corresponding MR is tracked in status.json. |
Sources: studio/src/lib/api.ts:28-50, studio/public/openapi.yaml:286-310
State Synchronization
The studio uses Server-Sent Events (SSE) via the /events endpoint to receive live updates. When the server detects changes in the reviews directory, status.json, or settings.json, it pushes a data: changed event.
The sequence diagram illustrates the live update mechanism triggered by file system changes.
Sources: studio/src/lib/api.ts:145-155, studio/public/openapi.yaml:215-220
Posting and Triage Flow
If ALLOW_POSTING=true is configured, the studio enables interaction with GitLab.
- Drafting: The user clicks "Add to review" on a finding, which calls
POST /api/postto create a GitLab draft note. - Tracking: Drafts are remembered in
posted.jsonto prevent duplicates and are shown with "In pending review" badges. - Submission: The user clicks "Submit review", opening a
ConfirmSubmitmodal. This callsPOST /api/submit-review, which executes abulk_publishof all draft notes. - Triage Fixes: For self-authored MRs, the triage command commits fixes locally. The studio's
FixesPanelchecks if these areready,pushed, oroutdatedagainst the origin branch.
Sources: README.md:173-181, studio/src/lib/api.ts:182-205, studio/public/openapi.yaml:122-145
Keyboard Shortcuts
Keyboard operation is a priority for efficient review handling.
| Shortcut | Action | Condition |
|---|---|---|
⌘K | Open Command Palette | Always |
⌘B | Toggle Sidebar | Review open |
Ctrl+W | Close active review tab | Review open |
⌘⌥W | Close active review tab | Review open |
Esc | Close modal or palette | Modal open |
Sources: studio/src/App.tsx:78-112, PRODUCT.md:73-75, DESIGN.md:300-305
Conclusion
Review Studio Overview describes a specialized local environment for digesting automated code reviews. By combining static file analysis with live GitLab integration, it allows developers to process high volumes of feedback while maintaining manual control over the final submission. Its architecture ensures that reviews are available offline and updated immediately as the background poller completes new analysis runs.
Sources: PRODUCT.md:35-42, README.md:15-20