Spaceflight Dynamics Framework Architecture

System Overview

The Spaceflight Dynamics Framework (SDF) is structured as a modular spacecraft simulation and research environment with a clear separation between the Qt-based frontend, the simulation worker thread, the backend-side simulation interface, and the backend simulation engine.

The overview intentionally shows only the main architectural building blocks. Detailed subsystem diagrams are provided separately for the frontend, backend, configuration flow, telemetry flow, propulsion, physics, and coordinate transformation layers.

The current architecture supports three-dimensional translational spacecraft motion and is being developed toward a full-state 6DOF-capable simulation framework. The backend already separates orchestration, spacecraft state, physics, propulsion, configuration interpretation, telemetry exchange, and coordinate frame transformation.

The Spacecraft component acts as the single source of truth for the simulation state. SimControl orchestrates the simulation flow, while the backend-side Simulation Interface Layer defines the stable communication boundary between the simulation engine and exchangeable frontend implementations.

Component Descriptions

• Frontend / UI Cockpit: Qt-based user interface containing the main window, cockpit page, landing visualization, user interaction, operator input, and presentation-oriented telemetry feedback.
• MainWindow: Top-level Qt application window responsible for page composition, navigation, and connecting frontend components to the simulation runtime.
• CockpitPage: Main simulation-facing cockpit view. It displays telemetry, forwards user interaction, and receives simulation updates from the worker-thread boundary.
• LandingView: Frontend visualization component for the current 2.5D landing and motion representation.
• ConfigManager: Frontend-side configuration component that selects and loads spacecraft configuration files before they are handed over to the simulation backend.
• JSON Config File: External spacecraft configuration source containing mass properties, initial conditions, fuel tanks, main engines, RCS engines, engine directions, engine positions, and engine-to-tank assignments.
• SimulationWorker: Worker-thread component that separates the UI thread from the simulation loop. It executes simulation steps outside the main thread and exchanges commands and telemetry through the Qt signal-slot mechanism.
• Simulation Interface Layer: Backend-side interface boundary between the Qt runtime and the simulation core. It defines the stable communication contract for frontend-to-backend commands and backend-to-frontend telemetry.
• FlightCommand DTO: Frontend-to-backend command object used to transport high-level operator or assistance commands into the simulation command path.
• TelemetryState DTO: Backend-to-frontend telemetry object intended to expose reduced, frontend-facing simulation state without leaking backend domain structures into the UI.
• Backend / Simulation Engine: C++ simulation backend containing the simulation core, spacecraft state representation, physics models, propulsion models, coordinate transformation logic, configuration interpretation, and telemetry generation.
• SimControl: Central simulation orchestrator responsible for simulation flow, command forwarding, validation, frame updates, and interaction with the spacecraft instance.
• Spacecraft: Core domain object and single source of truth for the simulation state. It owns the current state representation, spacecraft properties, propulsion state, physical state, and dynamic quantities required for force-based propagation.
• State Representation: Backend state structures describing the authoritative spacecraft state, including position, velocity, orientation, angular velocity, mass-related quantities, and simulation status.
• JsonConfigReader: Backend-side JSON interpreter that translates external configuration data into backend domain structures used to initialize the spacecraft and mission context.
• CoordinateTransformer: Backend coordinate transformation component for translating between simulation frames such as MCI, MCMF, MSC, ENU, LVLH, and SBF.
• Physics: Physical calculation orchestrator responsible for evaluating environmental and force-related models required for state propagation.
• Thrust: Propulsion calculation orchestrator responsible for main engine thrust, RCS thrust, fuel consumption, and propulsion state aggregation.
• Models and Abstract Model Interfaces: Extension points for concrete physics, propulsion, control, sensor, and optimization models. These abstractions allow individual simulation models to be replaced or extended without changing the complete backend architecture.
• Data Structs: Backend data containers used for exchanging simulation state, propulsion state, control input, telemetry values, and model-specific data inside the simulation engine.

Frontend Architecture

The frontend has been refactored into a clearer Qt application structure. MainWindow now acts as the central application shell and frontend coordinator. It owns the persistent top navigation bar, the central page stack, the shared configuration manager, and the simulation worker thread.

Individual pages are now treated as focused UI components rather than application controllers. The landing page only presents the project entry point and emits navigation requests. The spacecraft selection page handles configuration selection. The cockpit page handles telemetry visualization and operator interaction. Additional pages such as control help and settings can now be integrated without changing the overall navigation structure.

This structure reduces coupling between pages, prevents nested page stacks, and prepares the frontend for future expansion such as settings, telemetry inspection, replay views, ROS communication monitoring, and additional research-oriented tools.

Frontend Components

• MainWindow: Central Qt application shell. It owns the top bar, page stack, core pages, configuration manager, simulation thread, and worker interface.
• TopBarWidget: Persistent navigation bar for global frontend navigation, settings access, and control help access.
• QStackedWidget: Central page container used to switch between homepage, spacecraft selection, cockpit, controls help, and settings pages.
• Homepage: Pure landing page. It displays the SDF branding, development status, and primary entry points without owning worker threads or sub-pages.
• SpacecraftSelectionPage: UI page for selecting JSON-defined spacecraft configurations through the sharedConfigManager.
• cockpitPage: Main simulation cockpit page. It displays telemetry, forwards operator commands, and owns cockpit widgets such as LandingView and inputmapper.
• ControlsHelpPage: Static control reference page showing keyboard-first control bindings and planned controller readiness.
• SettingsPage: Placeholder page for the planned v0.2 SDF Research Release settings subsystem.
• inputmapper: Converts keyboard input into structured FlightCommand data.
• LandingView: Lightweight 2.5D visualization widget for spatial landing state, trajectory history, velocity vectors, and RCS activity indication.
• UIBuilder: Shared helper for consistent frontend UI elements, buttons, labels, page titles, and telemetry detail boxes.

Frontend Design Direction

• Centralized page routing through MainWindow
• Persistent global navigation through TopBarWidget
• UI pages with focused responsibilities
• No nested application windows inside the homepage
• Simulation worker ownership located at application shell level
• Preparation for future settings, help, telemetry, and ROS tooling pages

Backend Architecture

The backend of the Spaceflight Dynamics Framework (SDF) is designed as a modular simulation engine centered around a single authoritative spacecraft representation. It separates simulation orchestration, state management, coordinate transformations, propulsion modeling, physical state propagation, telemetry generation, and future optimization components into clearly defined subsystems.

At the center of the backend architecture is the Spacecraft component. It acts as the Single Source of Truth (SSOT) for the simulation state. The associated StateVector represents the dynamic state used for numerical propagation and is one of the most important runtime data structures in the simulation core.

SimControl acts as the central simulation orchestrator. It coordinates simulation execution, forwards commands, triggers subsystem updates, manages mission and frame context data, and controls the overall simulation lifecycle.

In the diagram, the orange-highlighted components represent the core simulation state path. Spacecraft and StateVector form the central runtime state authority. The pink-highlighted Thrust Optimizer represents a planned research-oriented extension for the future SDF v0.2 release.

Backend Components

• Simulation Interface Layer: Backend-side communication boundary between external frontend implementations and the simulation engine. It defines command and telemetry contracts and prepares the architecture for future frontend replacement and ROS-based communication.
• FlightCommand DTO: Frontend-to-backend command structure used to transfer operator input, assisted-control commands, main engine commands, and RCS commands into the backend command path.
• TelemetryState DTO: Backend-to-frontend telemetry structure used to expose reduced simulation state to visualization layers without leaking backend domain structures into the frontend.
• SimControl: Central simulation coordinator responsible for simulation lifecycle handling, command forwarding, subsystem coordination, mission context handling, frame context handling, and interaction with the active spacecraft instance.
• Spacecraft: Core backend domain object and Single Source of Truth for the current simulation state. It owns vehicle configuration, runtime state, propulsion state, physical state, and mission-related state data.
• StateVector: Primary dynamic state representation used by the simulation. It contains the propagated spacecraft state, including position, velocity, orientation, angular velocity, and additional dynamic state quantities.
• JsonConfigReader: Backend-side configuration interpreter that translates external JSON spacecraft configuration files into backend domain structures used to initialize spacecraft properties, engine configurations, fuel systems, initial conditions, and mission context data.
• CoordinateTransformer: Central backend component for coordinate and frame transformations between MCI, MCMF, MSC, ENU, LVLH, and SBF reference frames.
• Physics: Backend subsystem responsible for environmental force modeling, force aggregation, acceleration computation, numerical integration, and state propagation.
• Thrust: Propulsion subsystem responsible for main engine thrust, RCS thruster behavior, thrust allocation, fuel consumption, and resulting force generation.
• Models and Abstract Interfaces: Extension points for physics models, propulsion models, controllers, sensors, integrators, and future research models. These interfaces allow individual simulation models to be replaced without restructuring the backend.
• Telemetry Mapping: Backend mapping path that transforms simulation-internal state into frontend-facing telemetry DTOs.
• Thrust Optimizer: Planned SDF v0.2 research extension for optimization-based thrust, trajectory, guidance, and fuel-efficiency experiments. It is intentionally separated from the core real-time simulation loop.

Backend Design Direction

• SimControl orchestrates simulation flow, while Spacecraft owns the authoritative simulation state.
• Spacecraft and StateVector form the core runtime state path.
• Coordinate transformation is treated as a dedicated backend subsystem.
• Physics and propulsion are separated but connected through force generation and state propagation.
• Telemetry is transferred through explicit DTOs instead of exposing backend domain structures to the frontend.
• Optimization components are separated from the core loop and reserved for research-oriented SDF v0.2 functionality.

Physics Architecture

The physics architecture is centered around modular force models, numerical integration, sensor feedback, and control components. The current scope focuses on three-dimensional translational dynamics. Rotational dynamics and full rigid-body 6DOF propagation are planned future extensions.

Key Components and Relationships

• IPhysicsModel: Abstract interface for physical force or acceleration models.
• BasicMoonGravity: Current lunar central-body gravity model used to compute gravitational acceleration.
• IIntegrator: Abstract numerical integration interface used to propagate spacecraft states.
• EulerIntegrator: Current discrete-time integration implementation.
• Dynamics: Dynamics component used to combine forces, accelerations, and state propagation.
• IController: Interface for feedback control modules.
• PD Controller: Velocity-control component used for descent control and target tracking.
• IAutopilot: Interface for automated guidance and control logic.
• Adaptive Descent Controller: Energy-based landing controller using brake-ratio-guided mode switching and adaptive gain scheduling.
• InputArbiter: Control arbitration component that separates or prioritizes manual input and automated control commands.
• ISensor / SensorModel: Sensor abstraction and implementation used to compute telemetry quantities such as g-load and provide feedback for control and visualization.

Flow Summary

• The spacecraft provides the current physical state.
• Physics models compute environmental acceleration such as lunar gravity.
• Control and automation modules compute guidance or command outputs.
• The propulsion layer computes thrust forces from engine states.
• The dynamics and integrator components propagate the spacecraft state.
• Sensor models generate telemetry for feedback and frontend visualization.

Propulsion Architecture

The propulsion subsystem is built around a central Thrust Orchestrator. Instead of treating propulsion as a single scalar output, the system supports multiple engines, multiple tanks, engine-specific runtime states, RCS allocation, and vectorized thrust aggregation.

The main engine and RCS thrusters are modeled separately, but expose a common interface through IThrustModel.

Key Components and Relationships

• Thrust Orchestrator: Central propulsion manager. It registers engine models, forwards commands, updates engine states, computes fuel usage, and aggregates individual engine thrust into resulting force vectors.
• IThrustModel: Abstract propulsion interface for main engines and RCS thrusters. It defines common access to engine identity, command input, thrust output, direction, fuel consumption, and tank assignment.
• BasicMainEngineModel: Implemented main engine model. It represents the main engine as scalar thrust magnitude with response dynamics, target tracking, direction handling, and propellant consumption.
• BasicRCSModel: Implemented low-order model of one individual RCS thruster. It represents a binary valve-controlled actuator with command delay, first-order rise and decay dynamics, scalar thrust output, and propellant consumption.
• RCSControlAllocator: Allocation helper that maps axis-based RCS vector commands to individual thruster commands. The vector command determines which thruster direction is required; the individual thruster receives its local command.
• EngineConfig: Static configuration for main engines, including identity, tank assignment, thrust parameters, response parameters, direction, and mounting position.
• RCSEngineConfig: Static configuration for RCS thrusters, including identity, axis assignment, tank assignment, nominal thrust, command delay, rise and decay time constants, direction, and mounting position.
• ME_ThrustState: Runtime state of the main engine. The main thrust value is represented as a scalar magnitude, with direction stored separately for vector force construction.
• RCS_ThrustState: Runtime state of one individual RCS thruster. It contains metadata, scalar current thrust, scalar target thrust, normalized target command, actuator state, and thrust direction.
• FuelTank: Tank representation used to assign and track fuel resources.
• FuelState: Runtime fuel state used by engine models to compute and apply mass flow.

Flow Summary

• The JSON spacecraft configuration defines tanks, main engines, and RCS engines.
• The Thrust Orchestrator initializes one engine model per configured engine.
• Main engine commands are forwarded to the main engine model.
• RCS vector commands are mapped by the RCSControlAllocator to individual RCS thruster commands.
• Each engine model updates its own actuator state and fuel consumption.
• The Thrust Orchestrator combines scalar engine outputs with engine directions.
• The aggregated thrust vector is passed to the spacecraft dynamics model.

Command and Input Flow

Manual control input is processed separately from physical engine behavior. The frontend does not directly apply forces. Instead, operator input is converted into a command object, routed through the simulation control path, mapped to engine commands, and only then translated into physical thrust by propulsion models.

Current Command Path

• Keyboard input is captured by the cockpit frontend.
• The InputMapper converts key states into a FlightCommand.
• The command is forwarded through the current Qt signal-slot interface.
• SimControl and Spacecraft forward propulsion-relevant commands to the Thrust Orchestrator.
• The Thrust Orchestrator separates main engine and RCS commands.
• RCS commands are allocated to individual thrusters by the RCSControlAllocator.
• Engine models update actuator state, thrust output, and fuel consumption.
• The resulting thrust vector is used by the dynamics layer in the next simulation step.

Telemetry and Frontend Data Boundary

The current implementation still uses some backend structs in the frontend, for example fuel tank and simulation data containers. This is recognized as an intermediate state and will be refactored.

The target architecture introduces a strict boundary between backend domain models and frontend telemetry models. Backend structs describe simulation-internal state, while frontend DTOs describe only the data required for visualization and interaction.

Current Transition State

• Backend domain structs: Used internally for spacecraft state, thrust state, fuel state, configuration, and simulation data.
• Frontend datastructs: Used for cockpit-specific telemetry such as RCSCockpitTelemetry.
• TelemetryMapper: Planned mapping component that will translate backend state into frontend telemetry DTOs.
• Issue D19 Wrapper: Planned wrapper layer that will translate backend structs into frontend DTOs and later ROS message contracts.

Target Direction

• The frontend shall not depend on backend domain structs.
• The backend shall not depend on Qt frontend classes.
• Telemetry shall be transferred through explicit DTOs or ROS messages.
• The cockpit frontend shall be replaceable by another frontend without changing backend simulation logic.
• ROS will become the long-term communication interface between simulation backend and external consumers.

Optimization Components

The backend contains experimental optimization components based on NLopt. These components are currently used for thrust optimization experiments and are separated from the real-time control and propulsion path.

• OptimizationModelParams: Parameter container for optimization runs.
• OptimizationStruct: Data structure for optimization state and results.
• ThrustOptimizationProblem: Problem formulation for thrust optimization.
• ThrustOptimizer: Optimization driver using NLopt.

Architectural Design Principles

• Separation of Concerns: Input handling, command routing, control, propulsion, physics, telemetry, and visualization are separated into distinct components.
• Interface-Based Extensibility: Physics, sensors, controllers, autopilots, integrators, and thrust models are exposed through interfaces where appropriate.
• Configuration-Driven Setup: Spacecraft engines, tanks, mass properties, and initial conditions are loaded from external configuration.
• Explicit Runtime State: Engine states, spacecraft states, telemetry states, and fuel states are modeled explicitly.
• Vector-Based Dynamics: Propulsion output and motion propagation use vector quantities to support three-dimensional dynamics and future 6DOF extension.
• Frontend/Backend Decoupling: Direct dependency of the frontend on backend domain structs is temporary and will be replaced by DTO and ROS-based communication layers.
• Research Orientation: The system is designed for reproducible simulation runs, telemetry export, model validation, and future autonomous landing research campaigns.
• Open Engineering Philosophy: The project is developed as an open-source framework with emphasis on transparent architecture, modularity, reproducibility, and contribution-friendly evolution.