API Architecture
Review the NestJS API structure, module boundaries, runtime modes, and the role of health and realtime surfaces.
API Architecture
The API is the orchestration core of Noderax.
Responsibilities
- auth and sessions
- workspaces, memberships, and teams
- nodes, metrics, events, diagnostics, packages, tasks, and notifications
- terminal orchestration
- agent update rollouts
- control-plane update summary and request APIs
- realtime event distribution
Runtime modes
The API has two product modes:
- setup mode with
SetupAppModule - installed mode with
AppModule
The bundle chooses the correct root module during boot based on installer state and runtime role.
Architectural boundaries
The setup API exists only to validate bootstrap inputs, write install state, and trigger promotion into the installed runtime.
The installed API owns normal operator functionality: auth, nodes, metrics, events, diagnostics, terminals, notifications, rollouts, and control-plane update orchestration.
Some state transitions originate through the API but complete on the host, such as runtime promotion and control-plane bundle apply. The API coordinates but does not directly mutate the Docker runtime from inside the container.
Health model
Health routes exist both for operational dependency checks and for host-side promotion/update logic. Correct behavior depends on keeping setup and installed runtime probes distinct.
Setup health and installed-runtime health are intentionally different contracts. Treating them as interchangeable causes false positives during install and false negatives during promotion.