Skip to content

Architecture

This directory is the current architecture canon for bijux-cli.

The goal here is narrow: keep the smallest set of documents that explains the current system accurately.

What This Set Is

  • a description of the current Rust-owned system
  • a map of the workspace and its responsibilities
  • an explanation of how commands are parsed, executed, and emitted
  • a record of the state model, plugin model, packaging model, and maintainer control-plane
  • a description of how quality gates and architectural change are handled

What This Set Is Not

  • a migration diary from the older Python-owned runtime
  • a progress tracker
  • a parity scoreboard
  • a replacement for executable tests, schemas, or code-level contracts

Reading Order

flowchart TD
    A[index.md] --> B[system-overview.md]
    B --> C[workspace-map.md]
    C --> D[execution-pipeline.md]
    D --> E[routing-and-surfaces.md]
    D --> F[configuration-and-state.md]
    D --> G[plugin-system.md]
    C --> H[runtime-and-distribution.md]
    C --> I[maintainer-control-plane.md]
    I --> J[quality-and-change-management.md]

This flowchart is the recommended reading path through the architecture canon. It moves from the broad system picture into crate boundaries, then into the runtime subsystems, and ends with the maintainer and quality surfaces.

mindmap
  root((Architecture Canon))
    System
      System overview
      Workspace map
    Runtime
      Execution pipeline
      Routing and surfaces
      Configuration and state
      Plugin system
    Packaging
      Runtime and distribution
      Maintainer control-plane
    Governance
      Quality and change management

The mindmap shows the same canon grouped by topic instead of order. It helps a reader jump directly to runtime, packaging, or governance material once they already know the broad system shape.

The Ten Documents

  1. System Overview
  2. Workspace Map
  3. Execution Pipeline
  4. Routing And Surfaces
  5. Configuration And State
  6. Plugin System
  7. Runtime And Distribution
  8. Maintainer Control-Plane
  9. Quality And Change Management
  10. Architecture Index

Source Of Truth

These documents are explanatory, not normative by themselves.

The deeper sources of truth are:

  • the Rust source tree under crates/
  • the contract markdown under docs/07-contracts/
  • the machine-readable contract assets under contracts/
  • the executable tests
  • the published package surfaces

If one of these pages conflicts with the running code or the contracts, the page is wrong and should be corrected.

Current Architectural Claim

The current claim of this repository is simple:

  • bijux-cli owns the runtime
  • bijux-cli-python is a Python-facing packaging and bridge layer around the Rust runtime
  • bijux-dev-cli is the maintainer control-plane for repository and release diagnostics

That is the architecture being documented here.