Skip to main content

Source lifecycle UI

This page is for teams building source lifecycle screens on top of AetherFS.

Sources are the durable baseline side of the product.

What a source UI usually needs​

A good source lifecycle UI usually answers these questions:

  • What reusable sources exist?
  • What kind of source is each one?
  • Is the source ready, failed, or still changing?
  • What is the latest revision?
  • Is an import or refresh in progress?
  • Can a successful session be promoted into this source?

Core route families​

Use:

  • POST /v1/sources
  • GET /v1/sources
  • GET /v1/sources/{sourceId}
  • POST /v1/sources/{sourceId}/startImport
  • GET /v1/sources/{sourceId}/jobs/{jobId}
  • POST /v1/sources/{sourceId}/refresh
  • POST /v1/sources/{sourceId}/promoteSession

1. Source list page​

Show:

  • display name
  • source kind
  • source status
  • latest revision ID
  • updated time
  • useful labels

This page is usually driven by:

  • GET /v1/sources

2. Source detail page​

Show:

  • source metadata
  • latest revision
  • creation and update timestamps
  • current readiness
  • recent import or refresh activity
  • actions such as refresh or promote session

This page is usually driven by:

  • GET /v1/sources/{sourceId}

3. Job progress panel​

Import, refresh, and promotion are asynchronous.

That means a good UI should treat job progress as a first-class concept rather than pretending these actions complete immediately.

Use:

  • GET /v1/sources/{sourceId}/jobs/{jobId}

Show:

  • queued / running / succeeded / failed
  • bytes processed
  • files processed
  • revision ID on success
  • error code and message on failure

Source creation guidance​

At creation time, your UI should make clear:

  • what kind of source is being created
  • what durable baseline it represents
  • which labels or ownership metadata matter

A strong source creation form should separate:

  • display information
  • origin information
  • labels or classification

Refresh guidance​

Refresh should be treated as:

  • a request to update a durable baseline
  • an asynchronous job
  • a visible operation with progress and an eventual result

Do not model refresh as a simple “save” action.

Promotion guidance​

Promoting a session into a source is a high-leverage action.

It changes what future sessions may start from.

A good UI should show:

  • which session is being promoted
  • which source is being updated
  • the proposed revision label
  • whether approval or review has already happened

Status guidance​

Source status and source job status are different.

Keep them separate in the UI:

  • source status answers “is this source generally usable?”
  • job state answers “what is this current operation doing?”

Revision guidance​

Revision IDs are not just implementation detail. They are the user-facing anchor for repeatability.

Good UI patterns:

  • show latest revision clearly
  • show the resulting revision when a job succeeds
  • make it obvious when a new session will use that revision

Safe product defaults​

Use these defaults unless you have a strong reason not to:

  1. list sources separately from sessions
  2. show latest revision on the detail page
  3. show in-progress jobs as explicit async state
  4. require deliberate user confirmation before promotion

Source lifecycle anti-patterns​

Avoid:

  • hiding the async job model
  • hiding revision IDs entirely
  • treating source promotion as a casual session action
  • mixing session status and source status together as if they mean the same thing

See also: