Overview

• Orbitron is organised as a Rust Cargo workspace where each crate owns a distinct layer: data backbone, query language, GPU renderer, services, UI shells, automation CLIs, and an optional Python bridge.
• The user-facing binaries (orbitron, orbitron-viewer) are thin entrypoints over the shared core/* crates. The terminal UI is not a separate binary — it is folded into orbitron as orbitron view <file> --tui (automation/tui is a library the CLI depends on via its tui feature, on by default). orbitron-viewer (ui/shell/src/bin/orbitron-viewer.rs) is the desktop GUI, composing the same services with an egui/WGPU frontend; it is what cargo bundle ships as Orbitron Viewer.app.
• Public-facing library crates deny missing documentation locally. The central lint script denies warnings, unwrap/expect, and unsafe code across production targets; audited FFI and OS-handle boundaries use narrow local allowances with SAFETY comments.
• Reusable libraries use typed errors when callers need to distinguish failure modes. CLI, UI, and orchestration boundaries may use anyhow to add context.
• Prefer fallible parsing with Result/Option in production code: avoid unwrap/expect outside tests, log recoverable parser failures with tracing::warn, and surface actionable IoPipelineError::ParseError messages for malformed inputs.

Documentation layout

This Developer Guide is the authoritative architectural reference for contributors. For end-user workflows (installation, GUI usage, CLI commands), refer to the companion User Guide (published at https://orbitron.reackt.dev/user-guide/).