Skip to main content

Platform engineer guide

This guide is for people building products and internal platform tooling on top of the hosted AetherFS service.

This is not a guide to running afs-server.

It is a guide to designing good user-facing integrations against the public surface.

What matters most in this role​

As a platform engineer, the highest-signal concepts are:

  • source lifecycle
  • session lifecycle
  • review and approval boundaries
  • product role separation
  • API route-family selection
  • asynchronous jobs
  • reporting and visibility

Your core design problem​

Your job is usually to answer questions like:

  • When should a user get a new session?
  • When should a session become a source or commit?
  • Which actions need approval?
  • Which data belongs in annotations, cache, bus, events, or xattrs?
  • Which users should see reviewer UI versus Aether CLI mount workflows?

Read these pages first​

Start here:

Then use:

Product architecture guidance​

For most products, the strongest architecture is:

  • HTTP API for control-plane actions
  • Aether CLI only when users need local filesystem semantics

That means:

  • session creation over HTTP
  • review and approval over HTTP
  • reporting over HTTP
  • local editing through Aether CLI only when necessary

Good product defaults​

Use:

  • one session per task or proposal
  • forks for parallel work
  • checkpoints before high-risk changes
  • approvals before durable promotion
  • sources as reusable baselines

These defaults scale better than trying to keep one giant mutable workspace around forever.

Job model guidance​

Source import, refresh, and promotion are asynchronous.

Do not hide that from users.

Good product behavior:

  • show queued/running/succeeded/failed
  • show revision outcomes
  • surface errors clearly

Visibility model guidance​

Keep these concepts separate:

  • session status
  • health
  • analytics
  • usage
  • source readiness
  • job progress

Flattening them into one generic “state” label makes products confusing fast.

Secret model guidance​

Use the secret surface intentionally.

Do not:

  • mirror secrets into files by default
  • leak secret values into logs, annotations, or cache
  • treat tenant scope and session scope as interchangeable

Review model guidance​

Strong products separate:

  • comments on content
  • explicit approval state
  • durable persistence actions

That means:

  • annotations for comments
  • approval routes for decisions
  • commit/promotion routes for durable transitions

Common platform mistakes​

Avoid:

  • designing against undocumented routes
  • forcing Aether CLI into workflows that only need HTTP
  • treating session status as the only workflow state
  • hiding async jobs behind fake synchronous UI

Fastest useful platform-engineer toolkit​

If you only need one short reading path:

  1. operating model
  2. source lifecycle UI
  3. reviewer UI patterns
  4. examples
  5. secrets and scopes
  6. health, analytics, and usage