Skip to main content

Build a reviewer app

This guide is for teams building a reviewer-facing product flow on top of AetherFS.

The goal is not to expose every API route. The goal is to ship a usable review experience quickly and cleanly.

What you are building​

A basic reviewer app usually includes:

  • a review queue
  • a session detail page
  • a tree view
  • file-level comments
  • approval controls
  • health and history context

The minimum viable reviewer app​

If you want the smallest useful product, build these screens:

1. Review queue​

Show:

  • session label or task
  • current session status
  • last activity
  • whether approval is pending
  • last known health

Primary route:

  • GET /v1/sessions

2. Session review page​

Show:

  • session metadata
  • file tree
  • file content or file-aware review surface
  • annotations
  • approval controls

Primary routes:

  • GET /v1/sessions/{sessionId}
  • GET /v1/sessions/{sessionId}/manifest
  • GET /v1/sessions/{sessionId}/annotations

3. Comment and resolve flow​

Use:

  • POST /v1/sessions/{sessionId}/annotations
  • PATCH /v1/sessions/{sessionId}/annotations/{annotationId}

This gives you durable review notes and resolution state.

4. Approval flow​

Use:

  • POST /v1/sessions/{sessionId}/request-approval
  • POST /v1/sessions/{sessionId}/approvals/{approvalId}/grant
  • POST /v1/sessions/{sessionId}/approvals/{approvalId}/deny

Build in this order:

  1. session list
  2. session detail
  3. manifest tree
  4. annotation create/list/resolve
  5. approval controls
  6. health badge
  7. event history

That order gets a useful product in front of users without waiting for every possible supporting feature.

What to leave out at first​

Do not start with:

  • source lifecycle screens
  • low-level CAS extent views
  • xattrs
  • POSIX lock controls

Those are advanced surfaces. A reviewer app usually gets most of its value from sessions, manifests, annotations, approvals, and health.

Top-level review queue​

This is where reviewers decide which session to open next.

Session review page​

This is where real work happens.

Recommended layout:

  • header: session state, health, key actions
  • left pane: tree
  • center: file content or diff-aware review content
  • right pane: annotations and approval controls

History panel​

Use the event log for durable history.

Routes:

  • GET /v1/sessions/{sessionId}/events

How to use health​

Use health to support a reviewer, not to replace them.

Show:

  • passing / failing / unknown
  • passed / failed / skipped counts if present

Do not:

  • auto-approve just because health is passing

How to use annotations well​

Strong defaults:

  • show unresolved annotations prominently
  • anchor annotations to file and line
  • show the annotation status clearly
  • allow resolve/unresolve quickly

How to use deny feedback​

Approval denial should not be the only place detailed review feedback lives.

Use:

  • annotations for file-level detail
  • deny feedback for the high-level blocking reason

What success looks like​

A successful reviewer app lets a reviewer:

  • understand the workspace
  • see the relevant file tree
  • leave actionable notes
  • evaluate readiness
  • approve or deny with confidence