Skip to content

[T-001] Backend monorepo skeleton: uv project, package layout, ruff/mypy/pytest config, Makefile, pre-commit #12

Closed

Description

@CodewithJha

Task T-001 · Milestone M1 — Foundation · Size M · Priority P0 · Epic #1

Implements NFR-MNT-001 · NFR-MNT-002 · NFR-PORT-001 · NFR-COST-001

Branch chore/t-001-backend-monorepo-skeleton-uv-project — one task = one branch = one PR (doc 32 §6)

Summary

Create the Python side of the monorepo exactly as laid out in doc 16 §1 so that every later task has a place to put code, a lint/type/test toolchain, and make entry points.

Context / motivation

Nothing can be built until the repository has a buildable package, a locked environment and quality gates. Getting the tool configuration right once (ruff rules incl. PLR2004 magic-value rule, mypy strict, pytest markers) means every later PR is held to the same standard automatically. ADR-0004 fixes Python 3.12 + uv in a single monorepo.

Scope

In scope

  • backend/pyproject.toml for package roboprobe with extras [ml], [worker], [api], [dev] and the full dependency set from doc 15 §1 (so later tasks rarely touch the lockfile).
  • backend/src/roboprobe/ with empty sub-packages from doc 16 §1 (core, bootstrap, scenario, selection, oracles, analysis, risk, metrics, experiments, runner, backends, geometry, perturbation, store, api, reporting, cli) each with a docstring-only __init__.py.
  • backend/tests/{unit,integration,api,contract,property,benchmark,sim,e2e,fixtures}/ with conftest.py stubs.
  • Tool config in backend/pyproject.toml: ruff (line length 100, rule set from doc 16 §3, Google docstrings), mypy --strict, pytest markers unit, property, contract, integration, benchmark, sim, slow (default excludes sim and slow), coverage config.
  • Root Makefile with targets setup, lint, typecheck, test, test-fast (backend parts), .pre-commit-config.yaml (ruff, ruff-format, mypy, end-of-file, trailing whitespace, gitleaks).
  • Root .env.example and roboprobe.example.toml copied from doc 27 §5 with every key commented (values only; generator in T-003c will keep them in sync).
  • A trivial smoke test (tests/unit/test_import.py) so make test is green.

Out of scope

  • Web app (T-007)
  • Settings models (T-003a)
  • CI workflows (T-006a)
  • Docker (T-005a/b)

Implementation guidance

  • Use uv init --package semantics manually: [project] name = "roboprobe", requires-python = ">=3.12,<3.13", [build-system] hatchling, [tool.hatch.build.targets.wheel] packages = ["src/roboprobe"].
  • Extras (doc 16 §1, doc 15 §1): ml = torch (CPU), gpytorch, botorch, scikit-learn, shap; worker = pyarrow, pandas, lxml, jinja2; api = fastapi, uvicorn, sse-starlette; dev = pytest, pytest-cov, pytest-xdist, hypothesis, pytest-benchmark, testcontainers[postgres], mypy, ruff, import-linter, pip-audit, types-PyYAML. Base deps: numpy, scipy, pydantic, pydantic-settings, PyYAML, jsonschema, structlog, prometheus-client, sqlalchemy, alembic, psycopg[binary], typer, rich, uuid-utils, matplotlib.
  • Add the PyTorch CPU index via [tool.uv.sources] / [[tool.uv.index]] so CI never downloads CUDA wheels.
  • make setup → uv sync --all-extras --directory backend + pre-commit install; make test → uv run --directory backend pytest; make test-fast → -m "unit or property or contract" -n auto.
  • Commit backend/uv.lock (generated, never hand-edited — doc 16 §7).
  • Every module docstring must state its layer (doc 16 §2) so reviewers can spot violations.
  • Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff PLR2004); public APIs typed (mypy strict) and documented.

Acceptance criteria

  • make setup && make lint && make typecheck && make test pass on a clean clone (Linux and macOS).
  • Package tree matches doc 16 §1 (all sub-packages importable: python -c 'import roboprobe.selection').
  • ruff config enables the rule set listed in doc 16 §3 including PLR2004; mypy runs in strict mode on src/.
  • Pytest markers registered; pytest default run excludes sim and slow.
  • .env.example and roboprobe.example.toml exist, contain no secrets, and are referenced from README quick-start.
  • uv.lock committed; uv sync --locked succeeds.
  • Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
  • Docs, config reference and CHANGELOG Unreleased updated where behaviour, keys or interfaces changed.
  • Definition of Done (doc 32 §3) satisfied.

Tests required

  • tests/unit/test_import.py imports every sub-package.
  • Pre-commit hooks run clean on the whole repo.

Dependencies

Blocked by: nothing — can start immediately

Blocks: #13 (T-007), #14 (T-009), #15 (T-002a), #16 (T-002b), #17 (T-002c), #18 (T-002d), #19 (T-003a), #20 (T-008), #25 (T-017), #26 (T-005a), #28 (T-006a), #29 (T-006b), #32 (T-020a)

Parallelization notes

Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:

  • backend/pyproject.toml
  • backend/uv.lock
  • backend/src/roboprobe/**/__init__.py
  • backend/tests/**/conftest.py
  • Makefile
  • .pre-commit-config.yaml
  • .env.example
  • roboprobe.example.toml

Root task — everything else depends on it. Keep it minimal (no business logic) so it merges fast. After merge, pyproject.toml/uv.lock become shared hot files: later tasks that must add a dependency rebase and regenerate uv.lock (uv lock), never hand-merge it.

Definition of Done

Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-001 (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.

References

Design docs: doc 16 §1 · doc 16 §3 · doc 16 §7 · doc 17 §2 · doc 17 §3 · doc 15 §1 · ADR-0004 · doc 27 §5

Requirements: NFR-MNT-001 · NFR-MNT-002 · NFR-PORT-001 · NFR-COST-001 (traceability: doc 28)

External:

Activity

  1. added this to the M1 — Foundation milestone on Nov 19, 2026
  2. added
    type:choreMaintenance / scaffolding
    area:coreDomain core, plugin registry, shared types
    area:ciCI/CD workflows
    priority:P0Critical path / blocks others
    taskChild task of a milestone epic
    on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:ciCI/CD workflowsarea:coreDomain core, plugin registry, shared typesmilestone:M1M1 — Foundationpriority:P0Critical path / blocks otherssize:M1-3 daystaskChild task of a milestone epictype:choreMaintenance / scaffolding

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions