Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
51 lines (34 loc) · 2.14 KB

ARCHITECTURE.md

File metadata and controls

51 lines (34 loc) · 2.14 KB
Raw

Architecture

Goal

Keep a scientific Python project boring enough to reproduce.

The repository has one canonical gate: make verify. Both a developer and GitHub Actions build .devcontainer/Dockerfile and run the same locked checks. The host checkout is mounted read-only; verification copies it to /tmp/work before installing or generating artifacts.

Git checkout (read-only)
        │
        ▼
.devcontainer/Dockerfile
        │
        ├── Dev Container
        │
        └── make verify ── GitHub Actions
                 │
                 ▼
             /tmp/work
                 │
      uv sync --frozen (after initialization)
                 │
      ruff → pytest → Sphinx → smoke

Contracts

src/ layout

Importable code lives under src/<module>/. Tests import the installed package, not files by relative path.

Locked Python dependencies

uv.lock is generated by scripts/init_project.py after selecting a profile. Commit the lockfile. When it exists, make verify uses uv sync --frozen. The profile-neutral template can run without a lock and prints an explicit warning while resolving from pyproject.toml; generated research projects should keep the lockfile.

One container definition

.devcontainer/Dockerfile is used for interactive development and canonical verification. CI does not maintain a second package-install recipe.

Read-only source during canonical verification

make verify mounts the checkout at /work:ro, copies it into /tmp/work, and performs all installs/builds there. This catches tools that unexpectedly write into source while avoiding root-owned host artifacts.

Minimal profiles

The initializer offers generic, eda, ml, and api. A profile only chooses the first dependency/harness needed to prove the project works end-to-end. It is not an application framework and can be replaced immediately.

Why make local-verify also exists

Container verification is the reproducibility proof but is slower. make local-verify runs equivalent checks in the current uv environment for fast iteration. CI intentionally uses only make verify.