The Problem

Developers who want a repeatable, version‑controlled mechanical design for a heavy‑lift quadcopter must juggle CAD files, BOM spreadsheets, and assembly guides that live in separate, often binary‑only locations. Keeping those artefacts in sync and automating their generation is labor‑intensive and error‑prone.

What This Does

project-quiver stores the full mechanical definition of the Quiver PT3 drone as a build123d Python package under src/quiver/. The package programmatically composes STEP models, produces a Bill‑of‑Materials, and can be invoked from the command line via src/quiver/bom/__main__.py. Documentation, CAD assets, and test data live alongside the code in docs/, bom/, and flight-test/, so a single repository contains design, validation, and release artefacts.

Key artefacts:

  • src/quiver/bom/__main__.py – entry point that reads the assembly graph and writes bom/*.yaml.
  • src/quiver/airframe_structure/…/assembly.py – concrete Python modules that build the airframe geometry.
  • bom/*.yaml – canonical BOM files generated by the package.

How It Is Wired

Execution starts at python -m src.quiver.bom (or python -m quiver.bom after installing the package). The module:

  1. Parses the top‑level assembly defined in src/quiver/airframe_structure/assembly.py.
  2. Recursively imports the 50 internal Python modules (e.g., src/quiver/airframe_structure/landing_gear/assembly.py). The static import graph shows no circular dependencies and zero import edges beyond these modules, meaning each file is self‑contained.
  3. Calls the build() functions that invoke the build123d API to generate STEP files and a material list.
  4. Writes the resulting data to the bom/ directory via helper functions in src/quiver/bom/.

No external services, databases, or network calls are present; the only side‑effects are file writes under bom/ and optional STEP export under docs/. Because the import graph is flat, each module can be edited in isolation, but the measured analysis flagged deep nesting (up to 9 levels) in several assembly files, increasing cognitive load for future changes.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/project-quiver
cd project-quiver

# 2. Install the Python package (no lockfile is present – see Code Health)
pip install -e src

# 3. Generate the Bill of Materials
python -m src.quiver.bom   # writes *.yaml files into bom/

The repository includes a Makefile with a make bom target that runs the same command, and a sanity_checks.yml GitHub Action that validates the build on push.

Real‑World Use

A drone‑assembly line can invoke the package in a CI step to produce an up‑to‑date BOM before a production run:

- name: Generate BOM
  run: |
    pip install -e src
    python -m src.quiver.bom
- name: Archive BOM
  uses: actions/upload-artifact@v3
  with:
    name: quiver-bom
    path: bom/

The generated YAML feeds downstream ordering scripts without manual spreadsheet edits.

Code Health & Issues

  • HIGH – Commit a lockfile beside the manifest – src/pyproject.toml (no lockfile).
  • MEDIUM – Declare least‑privilege permissions for GITHUB_TOKEN – .github/workflows/cad_checks.yml.
  • MEDIUM – Enable Dependabot or Renovate – no update bot configured.
  • MEDIUM – Gate pull requests on a dependency vulnerability scan – no scan in CI.
  • MEDIUM – Move large binaries to Git LFS – e.g., src/quiver/equipment/pcb/steps/vendor/3310_main_pcb.step (94 MiB).
  • MEDIUM – Set persist-credentials: false on checkout – .github/workflows/cad_checks.yml.
  • LOW – Set timeout-minutes on workflow jobs – .github/workflows/cad_checks.yml.

Additional measured findings:

  • HIGH/cognitive_load – Deep nesting (max depth 9) in src/quiver/airframe_structure/landing_gear/assembly.py, docs/Operations/firmware/tattu-bridge/tattu_bridge.py, and src/quiver/attachments/designs/example_plate/assembly.py.
  • MEDIUM/clarity – Duplicated 6‑line blocks between src/quiver/equipment/pcb/assembly.py and src/quiver/equipment/peripheral/assembly.py.

No committed secrets were detected; a licence file is present.

The Bottom Line

project-quiver provides a fully version‑controlled, programmatic CAD pipeline that unifies mechanical design, BOM generation, and documentation. The code base is small and well‑isolated, but deep nesting and missing dependency lockfiles raise maintainability and reproducibility concerns. It is suitable for teams that need a scripted CAD workflow and are prepared to address the listed health items before using it in production.