Architectural Model¶

This page describes how the QSP package family is organized and why.

Design principles¶

The QSP ecosystem is built around four principles:

Shared foundation — All packages share a common type system defined in qsp-core. This enables outputs from one package to be used as inputs to another without type conversion.
Layered dependencies — Mid-tier packages (qsp-fft, qsp-filter, qsp-modulation, qsp-orientation) depend only on qsp-core. They do not depend on each other. This keeps the dependency graph acyclic and avoids coupling between unrelated concerns.
Separating primitives from workflows — qsp-core provides primitives. The mid-tier packages provide domain-specific tools. qsp-stack provides a convenient entry point to the full ecosystem. Users can start at any level.
Minimal surface — Each package does one thing well. A filtering package does not include modulation logic. An orientation package does not include spectral analysis. This makes each package easier to learn, test, and evolve independently.

Dependency graph¶

qsp-stack
├── qsp-core
├── qsp-fft       (depends on qsp-core)
├── qsp-filter    (depends on qsp-core)
├── qsp-modulation (depends on qsp-core)
└── qsp-orientation (depends on qsp-core)

qsp-core has no QSP dependencies. Every other package has exactly one QSP dependency: qsp-core.

Why not one package?¶

A monolithic package would be simpler to install but harder to maintain and evolve. Different users have different needs:

A navigation engineer needs qsp-orientation but not qsp-modulation
A communications engineer needs qsp-modulation and qsp-filter but not qsp-orientation
A researcher building a custom algorithm may only need qsp-core

A layered family allows each team to depend on only what they need. It also allows each package to evolve its own release cadence, versioning, and deprecation schedule without forcing changes on unrelated packages.

How workflows cross package boundaries¶

A typical QSP workflow might span several packages:

Sensor data
    → qsp-filter   (conditioning and noise reduction)
    → qsp-fft      (spectral analysis)
    → qsp-orientation  (attitude estimation)
    → application output

Or for a communications workflow:

Signal source
    → qsp-filter      (conditioning)
    → qsp-modulation  (symbol generation or demodulation)
    → output

Because all packages use the same type system from qsp-core, these handoffs are clean. There is no need to convert between incompatible array types or quaternion representations at package boundaries.

Separation from implementation¶

The QSP docs repository (qsp-docs) is intentionally separate from the implementation repositories. This keeps:

Docs freely updatable without touching implementation code
Implementation packages independently releasable
Example snippets in docs treated as illustrative, not as API contracts

This separation also makes it easier to evolve docs across multiple package versions.