Skip to main content

Design principles

The non-negotiables that shape every repo and PR.

1. One concept per repo​

Each repo solves one well-defined problem. If a feature is naturally part of two repos, it goes in the lower-layer repo (so both can use it) — or it lives in mts1b-platform.

Test: can you explain the repo's job in one sentence without "and"?

2. No duplication across repos​

We track 17 protected symbols (HRP, Black-Litterman, Kelly, Sharpe, walk-forward CV, Telegram dispatch, logging setup, ...) that must be defined in exactly one repo each. AST-based CI enforces this.

Why: across the source monorepo we found HRP in 4 places, Sharpe in 4 places, Telegram dispatch in 6 places. Each drift introduced a latent bug.

3. Light + focused over batteries-included​

A repo that does one job well is more useful than a repo that does ten jobs adequately. Prefer plugin extension points to feature flags.

Heuristic: if your repo is over 50k LoC, ask whether it should be two repos.

4. Foundation-first typing​

All cross-repo data crosses the boundary as a mts1b-foundation pydantic type. No tuples, no dicts-of-strings, no custom service-specific shapes leaking out.

Why: contract drift is the silent killer of multi-repo ecosystems. Foundation typing is the discipline that prevents it.

5. Apache 2.0 from day one​

All code is Apache 2.0. We accept code only from contributors who sign off (git commit -s), confirming DCO compliance.

Why: permissive licensing maximizes adoption. Apache 2.0 (vs MIT) explicitly grants patent rights, which matters for institutional adopters.

6. Multi-target deployment​

A repo is not "done" until it runs identically on Docker Compose, Proxmox LXC, Kubernetes (Helm), and the user's choice of cloud. The mts1b-deploy menuconfig is the single source of truth for how each repo runs.

Why: locking the ecosystem to one orchestrator forks the community.

7. Privacy + safety first​

  • No secrets in code, configs, or commit history (gitleaks CI gate).
  • No telemetry without explicit user opt-in.
  • Vault-managed secrets, never in .env files in repos.
  • All HTTP clients ship with a redact() filter so logs never leak credentials.

8. Reviewable AI assistance​

mts1b-githubbot posts AI reviews on every PR. The bot output is advisory, not authoritative — a human always merges.

Why: AI catches issues humans miss; humans catch issues AI hallucinates. Both layers required.

9. Boring CI​

Every repo runs the same CI stack:

  • pytest for tests
  • ruff for lint + format
  • mypy for typing
  • gitleaks for secrets
  • pip-licenses + scancode-toolkit for license audit
  • AST dedupe scan for protected symbols
  • Dependency direction lint

If CI passes, the code merges. If CI is red, the code does not merge. No exceptions.

10. The Proxmox LXC test bed​

Every release is validated end-to-end on Proxmox LXC before public release. This is the user's primary deployment target and the canonical smoke test for the ecosystem.

./mts1b-deploy install --target proxmox-lxc --profile foundational-12
./mts1b-deploy demo backtest-equities
# All 12 LXC containers green; demo backtest completes in < 5 minutes

If Proxmox is green, we ship.