Skip to content

Contributing

Repository layout

AnnoTrain/
├── backend/
├── frontend/
├── docs/
├── data/
│   └── .gitkeep
├── README.md
└── .gitignore

Development principles

  1. Keep the implementation incremental — build the smallest usable version first.
  2. Do not implement future roadmap features unless explicitly requested.
  3. Prefer simple, readable code over premature abstractions.
  4. Keep the backend generic: never hard-code animal, root, cell, etc. into core domain models (see the data model).
  5. Separate annotation logic from ML/training logic (see architecture).
  6. Preserve future support for classification, detection, segmentation, points, paths, and tracking.
  7. Treat raw annotations, consensus datasets, dataset versions, and model versions as different concepts.
  8. Never store large scientific images or model weights in Git.
  9. Never commit secrets or .env files.
  10. Add documentation as functionality is implemented.
  11. Prefer reproducibility and explicit versioning.
  12. Keep the MVP deployable and understandable by one researcher maintaining the project.

UX principles

Contributor workflows should require minimal friction. For the initial classification workflow:

Open project URL → image appears → choose label → annotation saved → next image

Contributor accounts are not required for the MVP. Researcher-facing interfaces can be more detailed, but scientific/ML terminology should be explained rather than assumed.

Pedagogical principles

Whenever practical, expose concepts rather than hiding them completely — e.g. show how many annotations produced a consensus, dataset split sizes, class imbalance, model probabilities, confusion matrices, disagreement, model errors, and which DatasetVersion trained which ModelVersion. The platform should make deep learning understandable without making the interface unnecessarily technical.

Storage rules

Git must never be used for scientific datasets, credentials, or large trained-model files. The .gitignore already excludes local data, databases, model checkpoints, logs, and environment files — keep it that way as the project grows.

Documentation strategy

Documentation is written alongside the software, not after it. This docs/ site is the seed of the public AnnoTrain documentation — add a page as soon as the corresponding functionality starts to exist, following the structure already used here (Vision, Annotation, Architecture, Roadmap).