Architecture

This guide describes the current voiage implementation shape so contributors can extend it without breaking the public contract.

Module structure

  • voiage.schema holds the structured in-memory contract objects.

  • voiage.analysis provides the orchestration layer and the DecisionAnalysis facade.

  • voiage.methods contains the method implementations.

  • voiage.plot contains plotting helpers that stay separate from calculation logic.

  • voiage.cli exposes the command-line surface for the public workflows.

Backend abstraction

The library keeps the computational backend behind a small dispatch layer. NumPy remains the default runtime path, while JAX is an optional acceleration backend rather than a user-facing contract requirement.

The key rule is that the backend should not change the analysis semantics. Only performance and execution details are allowed to vary.

DecisionAnalysis flow

The central flow is:

input -> schema -> method -> result -> plot/CLI output

DecisionAnalysis accepts raw arrays or schema objects, normalizes them into the shared data structures, and then routes calculations through the public method surface. This keeps the user-visible API thin while preserving a single source of truth for validation and result formatting.

Data flow and boundaries

  • Inputs should enter through schema objects where possible.

  • Methods should return structured result objects for multi-field analyses.

  • Plotting should consume result objects rather than recomputing analysis.

  • CLI commands should compose the public analysis methods instead of reimplementing them.

When you add a new feature, keep the implementation in the narrowest layer that owns the behavior. Contracts and validation belong in schema or the relevant spec; orchestration belongs in analysis; numerical logic belongs in methods.