API architecture

What this page is

The shape of the HTTP interface: 46 endpoints over an in-memory store, a three-code error model, and a set of hard limits that decide which measurements can be made here and which cannot.

State is a single in-memory store

type AppState = Arc<Mutex<Store>>;
 
struct Store {
    constellations: HashMap<String, Constellation>,
    scenarios: HashMap<String, StoredScenario>,
}

Two consequences follow directly, and both matter operationally.

The service is therefore a single-instance analysis backend, not a horizontally scalable one. Treating it otherwise produces failures that look intermittent and are not.

The lock is not held during computation

The obvious worry with one mutex over all state is that a long analysis blocks every other request. It does not, because handlers take the lock only to clone what they need:

let constellation = {
    let store = state.lock().expect("store mutex poisoned");
    store
        .constellations
        .get(&req.constellation_id)
        .cloned()
        .ok_or_else(|| ApiError::not_found(/* ... */))?
};
 
// lock released here; the expensive work happens after

Cloning a constellation costs memory proportional to the satellite count and buys concurrent analysis. For a 5000-satellite ceiling that is a sound trade.

Errors are three codes and a message

struct ApiError {
    status: StatusCode,
    code: &'static str,
    message: String,
}

Rendered as:

{ "error": { "code": "invalid_request", "message": "..." } }

The entire vocabulary is three codes:

unknown propagation_model `two-body` (expected `two_body`, `j2`, `sgp4`,
`numerical`, or `ephemeris`)

constellation `ph1` not found; generate it first

grid has 64800 points, exceeding the limit of 40000; use a coarser grid_deg
or a smaller region

Validation happens before the expensive work

Handlers check bounds, build and validate the grid, and only then touch the store and run the analysis. The comment in the coverage handler states the intent plainly:

// Build and validate the grid up front so an over-fine request is rejected
// before the (expensive) simulation runs.

That ordering is why an over-large coverage request fails in milliseconds rather than after a minute of work.

The limits are the interesting part

Every endpoint is bounded. These are the constants, read from the source.

These exist because the service is shared and a single request must not be able to consume it. That is the right instinct. But the specific values have a consequence worth stating directly.

Some measurements cannot be converged here

Compare the API’s ceilings against what BER sweeps and coding gain and measured MODCOD thresholds actually needed.

The API says so itself. The rejection message is:

frames must be 1..=12 (CLI for higher confidence)

That parenthetical is the architecture stating its own division of labor:

• The API is for exploration. Interactive, bounded, safe to expose, fast enough to sit behind a UI.
• The CLI is for results you intend to quote. Unbounded, local, as slow as the measurement requires.

Route layout

46 endpoints, grouped by leading path segment. The largest groups:

The remainder are single endpoints: /simulate, /coverage, /eclipse, /isl, /econ, /trade, /replan, /transfer, /stationkeep, /conjunction, /platform, /stations, /orbits, /export, /ephemeris, /fleets, /constellations, and /health.

/scenarios is the largest group because a stored scenario is exposed in four representations, its CZML, OEM, ephemeris CSV, and contacts CSV, alongside the scenario itself. It and /fleet/snapshots/{id} are the only routes with path parameters; everything else is a POST with a JSON body.

Two spelling conventions

Deploying it

Given the state model, the operational shape is fixed:

1. One instance. Do not scale horizontally without an external store.
2. Expect cold restarts to lose state. Anything durable belongs in files the client keeps.
3. The limits are per request, not per client. Nothing here rate-limits a caller, so put that in front if the service is exposed.
4. No authentication is built in. The only middleware in the router is request telemetry. There is no auth layer and no CORS layer, so the service assumes a trusted network or a gateway that supplies both.

Next steps

• Crate boundaries for what sits beneath the routes.
• API reference for the endpoints themselves.
• System overview for analysis flow.