Skip to content

REPO_LAYOUT.md

Latest commit

 

History

History
100 lines (80 loc) · 7.78 KB

REPO_LAYOUT.md

File metadata and controls

100 lines (80 loc) · 7.78 KB
Raw

Repository Layout

This file documents the top-level repository layout outside docs/ and src/. Those two directories are treated as stable documentation and source-code roots and are intentionally out of scope for this cleanup pass.

Review mark format:

  • Reviewed 2026-06-18: role and cleanup policy checked in this pass.
  • External: managed outside this repo cleanup policy.
  • Ignored: local artifact/runtime path covered by .gitignore.

Stable Project Roots

Path Role Notes Review
configs/ Runtime and evaluation configuration Presets live in configs/presets/; mamba_whole_graph.yaml is the current frozen main-line preset. configs/shipping/ holds the resolved shipping config the native builders consume (decision_relevant since #465 PR-4b). Reviewed 2026-10-03
include/ C++ / CUDA public headers Native tracking, media, perception, and package-facing headers. Reviewed 2026-06-18
scripts/ Reusable command-line tools Evaluation, training, native build helpers, benchmarks, and model tooling. Every script carries a # status: label and a docstring; see the generated docs/ownership/scripts_inventory.generated.md (or each dir's README.md) for the function/status index, and scripts/README.md for the cleanup ledger. Reviewed 2026-07-21
tests/ Test suites Unit, integration, native, benchmark, golden, and experimental tests. Reviewed 2026-06-18
shipping/ Python-free shipping runtime (native) saccade_shipping_config: strict loader for configs/shipping/*.resolved.json (#465 PR-4a); saccade_shipping_native_config: CUDA-free JSON → tracker-parameter mapping and readback; saccade_shipping_native: builds the GPU tracker/GMC/pipeline from the resolved config and fails closed on readback (PR-4b). post_detector_*: the native post-detector replay host (NMS → detection filters → GMC → tracker, serial) and tools/saccade_replay (developer replay of a Python dump, PR-5 / U3a). decision_relevant since PR-4b; built standalone (CPU CI) and from the root build. Reviewed 2026-10-03
tools/ Developer coordination tools (not pipeline code) resctl.py: cross-worktree GPU / CPU / benchmark leases and handoffs; state lives in .git/worktree-runtime/, never tracked. See docs/WORKTREE_RESOURCES.md. Reviewed 2026-09-18
third_party/ Vendored external code Currently includes TrackEval. Avoid mixing local experiment output here. Reviewed 2026-06-18
docker/, Dockerfile, docker-compose.yml Container entry points Keep deployment/build container changes here. Reviewed 2026-06-18
infra/ Local infrastructure config PostgreSQL/systemd and service-level support files. Reviewed 2026-06-18
.github/, .githooks Repository automation CI and local git hook material. Reviewed 2026-06-18
CMakeLists.txt Native build entry point Keep at repo root. Reviewed 2026-06-18
pyproject.toml, uv.lock, .python-version Python project metadata Keep at repo root. Reviewed 2026-06-18
main.py Legacy/manual app entry point Keep until confirmed unused; do not create new root scripts beside it. Reviewed 2026-06-18
build_fpn_reid.py Moved native helper Moved to scripts/native/build_fpn_reid.py; root copy removed. Reviewed 2026-06-18

Data, Models, And Runtime State

Path Role Git policy Review
datasets/ Local datasets such as MOT17, DanceTrack, SportsMOT, CrowdHuman Ignored. Large local data only. Reviewed 2026-06-18
models/ Model metadata and local model binaries Metadata and placeholders may be tracked; large weights/engines are ignored. Reviewed 2026-06-18
storage/ Local service state Runtime storage such as PostgreSQL and MLflow artifacts should stay ignored. Reviewed 2026-06-18
.venv/ Local virtual environment Ignored. Recreate with uv sync. Reviewed 2026-06-18
.env, .env.example Local/private env and template .env ignored; .env.example tracked as template. Reviewed 2026-06-18

Generated Outputs

These directories are local experiment/runtime output. They are not source of truth unless a result is explicitly promoted into a tracked report or decision.

Path Role Cleanup rule Review
out/ Short-lived evaluation outputs Safe to delete after important results are summarized elsewhere. Reviewed 2026-06-18
output/ Historical evaluation/sweep outputs Safe to prune after preserving useful metrics. Reviewed 2026-06-18
results/ Evaluation result directories Large local artifact root; promote only summaries/tables. Reviewed 2026-06-18
runs/ Training and experiment runs Large local artifact root; keep only active checkpoints locally. Reviewed 2026-06-18
logs/ Runtime logs Safe to rotate/delete. Reviewed 2026-06-18
reports/ Generated report exports Regenerable unless manually curated. Reviewed 2026-06-18
build/, build-native-coverage/, dist/ Build artifacts Regenerable. Delete when stale. Reviewed 2026-06-18
.cache/, .mypy_cache/, .pytest_cache/, .ruff_cache/ Tool caches Regenerable. Reviewed 2026-06-18
*.sqlite, *.prof, *.nsys-rep, root *.so Profiling/native build artifacts Ignored. Delete or regenerate locally. Reviewed 2026-06-18

Report Material

Path Role Notes Review
report_data/ Tracked paper/report source material Contains curated tables, figures, and report notes. Generated JSON is ignored. Reviewed 2026-06-18
README.md Public project entry point Keep synchronized with accepted project direction and frozen headline numbers. Reviewed 2026-06-18
DEVELOPMENT.md Developer thin entry Need levels D0–D4 → action cards → doc combos + commands; no live status; details live elsewhere. Reviewed 2026-07-13
REPO_LAYOUT.md Top-level repository map Update when a top-level directory changes role. Reviewed 2026-06-18
LICENSE License text Keep at repo root. Reviewed 2026-06-18

Scratch And One-Off Work

Path Role Rule Review
scratch/ Exploratory scripts and validation snippets Use for one-off experiments that are not ready for scripts/. Reviewed 2026-06-18
root-level debug_*.py, patch_*.py, test_*.py, trt_bench.py Temporary local scripts Ignored unless explicitly tracked. Promote reusable code into scripts/ or tests into tests/; root copies were moved to scratch/root_artifacts_20260618/. Reviewed 2026-06-18
1 Removed tracked stray file Contained a stale log/tail fragment, not a project entry point. Reviewed 2026-06-18

Explicitly Out Of Scope

Path Reason Review
docs/ User requested no cleanup in this pass. Out of scope 2026-06-18
src/ Directory map and language bridge: src/README.md. This layout file still does not inventory src/. Out of scope 2026-06-18; map added 2026-09-11
.git/ Git internal state. External
.agents/, .codex/, .gemini/ Agent/tool-local metadata. External

Cleanup Order

When the workspace is noisy, clean in this order:

  1. Delete stale build/cache artifacts: build/, build-native-coverage/, .mypy_cache/, .pytest_cache/, .ruff_cache/, .cache/.
  2. Prune old generated outputs: out/, output/, results/, reports/, logs/.
  3. Prune inactive training runs under runs/ after checkpoint provenance is captured in report_data/ or the relevant research note.
  4. Move reusable root-level debug scripts into scripts/ or tests/; leave truly one-off probes in scratch/.

Do not move datasets/ or models/ as part of cleanup. They are intentionally large local roots and often referenced by scripts.