Skip to content

REPOSITORY_LAYOUT.md

Latest commit

 

History

History
76 lines (58 loc) · 3.73 KB

REPOSITORY_LAYOUT.md

File metadata and controls

76 lines (58 loc) · 3.73 KB
Raw

Repository layout and generated artifacts

This repository keeps source code, deterministic test fixtures, generated runtime data, and historical research artifacts in separate areas. The goal is to make day-to-day development reproducible while still preserving research outputs that are useful for comparison.

Path classification

Path Classification Ownership
src/ Source Runtime packages, server/client code, protocol code, and checked-in model tooling.
tests/ Fixture and test source Small deterministic fixtures required by automated tests.
docs/ Source Maintained documentation.
scripts/ Source Analysis, simulation, example, and maintenance commands.
data/models/ External/runtime metadata Model timing metadata and offloading metadata. Keep only small deterministic metadata that is required by tests or examples.
data/results/ Generated output Simulation runs, evaluations, plots, reports, and generated CSV/JSON outputs. Ignored by default for new files.
data/runtime_inputs/ Generated output Request images or other transient runtime inputs captured while the server is running.
logs/ Generated output Runtime logs and profiling outputs.
reports/ Generated output Local and CI reports such as JUnit XML or coverage artifacts.
archive/ Research archive Historical source snapshots or migration reference material that should not be imported by runtime code.
analisi test/, grafici*/, simulated_results/ Research archive Historical experiment snapshots. New experiment output should go under data/results/ unless deliberately archived.
mini_dataset/, datasets/, sciot-fomo-models-export/ External artifact Dataset/model exports. Prefer external storage for large artifacts and keep only tiny deterministic fixtures in Git.

Canonical generated-output directories

New code should use these directories:

  • Model/offloading metadata: data/models/
  • Evaluation CSV files: data/results/evaluations/
  • Simulation runs: data/results/simulation_<timestamp>/
  • Runtime request inputs: data/runtime_inputs/
  • Logs and profiler data: logs/
  • Test/coverage reports: reports/

The server centralizes these paths in server.commons.RuntimePaths. The default root is data/, and these environment variables can redirect outputs:

  • SCIOT_OUTPUT_DIR
  • SCIOT_MODEL_METADATA_DIR
  • SCIOT_RESULTS_DIR
  • SCIOT_LOG_DIR
  • SCIOT_RUNTIME_INPUT_DIR

Use overrides for CI runs, Docker volumes, and one-off experiments instead of hard-coding script-specific output paths.

Migration notes

Existing historical research folders remain in place to avoid a disruptive repository shuffle. Treat them as read-only archives. When touching those outputs, either migrate the result to data/results/ or move the historical snapshot to external storage as part of a dedicated cleanup change.

New generated outputs are ignored by default unless intentionally promoted to a small deterministic fixture. If an artifact is needed by tests, place it under tests/fixtures/ or tests/test_samples/ and document why it is stable.

Cleanup procedure

To remove local generated data without deleting source files:

rm -rf logs reports data/results data/runtime_inputs .pytest_cache htmlcov .coverage

Then regenerate only the artifacts needed for your current experiment or test run.

CI guardrail

scripts/check_repository_artifacts.py --changed rejects newly added files that match common generated-output patterns or exceed the default size limit. This keeps accidental logs, profiler dumps, datasets, and generated simulation results out of new pull requests while allowing the current historical archive to be migrated separately.