Repository Structure

Overview

All project code lives under the tlbox/ top-level directory. This is a language-agnostic namespace — Python, C++, Rust, hardware, and documentation all coexist under it. The namespace doubles as the Python package name and is reserved on PyPI, BCR, and npm for future publishing.

Build infrastructure, platform definitions, and vendored dependencies live outside tlbox/ at the repo root.

Directory Map

tlbox/                  # all project code
  algorithms/           # standalone algorithm implementations
  apps/                 # runnable applications and CLI tools
    bazel_parser/
    code_metrics/
    ...
  hw/                   # hardware-adjacent code
    drivers/            # C++ hardware drivers
    services/           # C++ hardware services / RPC
    ee/                 # electronics schematics (KiCad)
  notebooks/            # Jupyter notebooks
  ansible_playbooks/    # system configuration and provisioning
  scripts/              # one-off scripts
  testing/              # shared C++ test infrastructure (gtest_main, pw_log handler)
  utils/                # shared libraries and utilities (Python + C++)
bzl/                    # custom Bazel rules
tools/                  # build tooling (formatters, linters, Bazel wrappers)
platforms/              # Bazel platform and toolchain definitions
third_party/            # vendored dependencies
examples/               # reference implementations and demos
nobazel/                # experiments outside the build system
docs/                   # documentation (this site)

Rules of Thumb

Where does new code go?

What you’re adding	Where
A new runnable tool or CLI app	`tlbox/apps/<name>/`
A reusable library (any language)	`tlbox/utils/` or a new domain subdir
Hardware driver or service	`tlbox/hw/drivers/` or `tlbox/hw/services/`
Electronics schematic	`tlbox/hw/ee/`
A notebook	`tlbox/notebooks/`
A one-off script	`tlbox/scripts/`
A formatter, linter, or Bazel wrapper	`tools/`
A custom Bazel rule or macro	`bzl/`
A vendored external dependency	`third_party/`
A reference implementation or demo	`examples/`

When to create a new subdirectory under tlbox/: when you have a clearly distinct domain that doesn’t fit an existing category. Three related modules sharing a domain is a reasonable threshold.

Language is not a directory boundary. C++, Python, and Rust for the same domain live together. A hardware driver’s .cc, .h, .py bindings, and .proto definitions all belong in tlbox/hw/drivers/<name>/.

The `tlbox/` Namespace

Python

tlbox is a namespace package — no __init__.py files are needed. Python 3 resolves the namespace implicitly.

Imports use the full tlbox.* path:

from tlbox.utils.graph_algorithms import weighted_sample
from tlbox.apps.bazel_parser.parsing import parse_build_graph

Bazel manages PYTHONPATH hermetically via imports attributes on py_library targets — no manual path manipulation needed.

Why not `src/`?

src/ is a Python packaging convention that prevents accidental imports when running Python directly from the repo root. In a Bazel repo, imports are managed hermetically, so src/ adds label verbosity (//src/tlbox/...) with no benefit.

Name selection

Several names were evaluated against PyPI, BCR, and npm before settling on tlbox:

Name	PyPI	Notes
`tbx`	taken
`tbox`	taken
`tlbx`	taken
`toolbox`	taken
`tlbox`	free	chosen

tlbox is also free on BCR and npm.

What Stays Outside `tlbox/`

Directory	Reason
`bzl/`	Bazel rules are build infrastructure, not project code
`tools/`	Formatters, linters, Bazel wrappers — build tooling only
`platforms/`	Bazel platform constraints and toolchain configs
`third_party/`	Vendored deps — conventional top-level location
`examples/`	Demos are not library code; kept separate to avoid noise in API docs
`nobazel/`	Explicitly outside the build system