Backend API Services

Relevant source files

The following files were used as context for generating this wiki page:

• studio/public/openapi.yaml
• studio/src/lib/api.ts
• README.md
• PRODUCT.md
• studio/src/components/SettingsPage.tsx
• studio/src/lib/reviewSections.ts

Backend API Services provide a local communication layer between the Marginalia studio (React frontend) and the underlying automation processes. The server, defined in studio/server.mjs, binds to 127.0.0.1 and manages interactions with review files, status.json, and the GitLab API using a personal GITLAB_TOKEN. It acts as a bridge for listing reviews, managing settings, and triaging merge request fixes.

Sources: studio/public/openapi.yaml:5-10, README.md:155-165, PRODUCT.md:21-25

Architecture and Data Flow

The backend operates as a local-only service. It exposes RESTful endpoints for the frontend and uses Server-Sent Events (SSE) to notify the studio of file system changes. When a review file, status.json, or settings.json changes, the server broadcasts a changed event, triggering the studio to refresh its data.

The diagram shows how the server mediates between local data generated by the bot and the user interface.
Sources: studio/public/openapi.yaml:10-15, studio/public/openapi.yaml:314-318, README.md:175-180

Core API Modules

Review Management

The service provides endpoints to list and retrieve machine-generated reviews. A "Review Shape" is normalized by lib/findings.mjs so the studio displays consistent data regardless of which specific Claude command generated the report.

Endpoint	Method	Description
/api/reviews	GET	Lists all reviews and current bot status.
/api/reviews/{slug}	GET	Returns a specific review's Markdown and structured data.
/api/history/{slug}	GET	Lists previous versions of a review kept in .history.

Sources: studio/public/openapi.yaml:26-94, studio/src/lib/api.ts:89-100

Pending Review Flow (Opt-in)

If ALLOW_POSTING=true is set in the environment, the backend enables interaction with GitLab's draft system. This allows users to stage comments locally before publishing them as a bulk review.

This flow illustrates the draft-and-publish mechanism for merge request comments.
Sources: studio/public/openapi.yaml:17-23, studio/public/openapi.yaml:138-195, studio/src/lib/api.ts:206-228

Triage and Fixes

For merge requests authored by the user, the bot runs a triage command that can commit fixes locally. The API tracks these fixes and allows pushing them to the remote branch if fast-forwarding is possible.

• Status Tracking: Compares the local marginalia/<branch-slug> branch against origin.
• States: none, ready (pushable), pushed, or outdated (remote branch moved).
• Pushing: Executes git push only when ALLOW_PUSH=true and no force-push is required.

Sources: studio/public/openapi.yaml:262-311, studio/src/lib/api.ts:285-310

Configuration and Settings

Settings are stored in settings.json and can be updated at runtime without restarting the bot. The backend merges these values with .env defaults.

// studio/src/lib/api.ts:182-187
export interface Settings {
  pollIntervalMinutes: number;
  staleAfterDays: number;
  allowedTargetBranches: string[];
  excludeAuthors: string[];
}

Setting	Type	Description
pollIntervalMinutes	Integer	Frequency of MR polling (1-1440).
staleAfterDays	Integer	Days of inactivity before an MR is ignored.
allowedTargetBranches	Array	Filter for specific branches (e.g., main).
excludeAuthors	Array	Usernames whose MRs are never reviewed.

Sources: studio/public/openapi.yaml:113-136, studio/src/components/SettingsPage.tsx:15-20

Security and Constraints

The API implements several security measures for local operation:

• Origin Protection: Write endpoints (PUT, POST, DELETE) validate the Host and Origin headers to prevent DNS-rebinding and cross-site attacks.
• Local Binding: The server binds exclusively to 127.0.0.1.
• Opt-in Writes: Destructive or public-facing actions (posting to GitLab, pushing code) return 403 Forbidden unless specifically enabled in the environment.
• Content Type: All requests with a body must use application/json.

Sources: studio/public/openapi.yaml:7-15, studio/public/openapi.yaml:328-348