Skip to content

Roadmap

Mişko starts as a video-only behavioral test platform. There are no sensors in the core roadmap. All measurements are derived from camera frames, calibration, apparatus geometry and code-backed paradigm specs.

Camera frame
-> detection or segmentation
-> tracking
-> pixel-to-cm calibration
-> trajectory in apparatus coordinates
-> zone and event metrics
-> quality-control metrics
-> validated summary result in Mişko
  • Superadmin bootstrap at Docker startup.
  • Public sign-up removed.
  • Internal user management.
  • Laboratory singleton: one lab per installation. ✅
  • Installation wizard creates the lab and SUPERADMIN together (CLI, Docker startup). ✅
  • A second laboratory is refused (singleton guard). ✅
  • Five roles: SUPERADMIN, LAB_MANAGER, RESEARCHER, TECHNICIAN, VIEWER. ✅
  • Code-defined permission matrix with requirePermission(...). ✅
  • Environment instances: named, persisted test setups created from a paradigm template (many per paradigm). ✅

Done: Laboratory singleton and Environment models + migrations; the installation wizard (backend/prisma/bootstrap-admin.js) creates the lab and superadmin together. Lab API: GET/PATCH /api/lab (lab:configure). Paradigms are read-only, code-owned templates served by GET /api/paradigms and GET /api/paradigms/:key. An environment is a named instance of a paradigm whose physical values are resolved into a self-contained snapshot ({ paradigmKey, schemaVersion, apparatus, zones }); the values are validated against the code-fixed parameter ranges and stay locked at test time. Environment API: GET /api/environments, GET /api/environments/:id, POST /api/environments, PATCH /api/environments/:id, DELETE /api/environments/:id (writes need apparatus:write). A lab can hold several environments per paradigm (e.g. two distinct Morris water tanks). The frontend exposes an Environments menu; the Paradigms page is a read-only catalog, and each paradigm detail page can spawn a new environment.

  • Code-backed ParadigmSpec registry (4 paradigms): MWM, NOVEL_OBJECT, POLE, TREADMILL. On 2026-10-15 the catalog was trimmed to these four; the other seven paradigms were removed. ✅
  • Code-backed metric dictionary from Measurement architecture. ✅
  • Canonical units: results use cm, cm_s, s, count, ratio, percent, deg, g, boolean; apparatus parameters add mm and c. ✅
  • Per-paradigm parameters, zones, metrics, QC requirements and artifact expectations. ✅
  • Per-metric valueType / validRange / templated (zone-keyed) - the contract both manual entry and CV validate against. ✅
  • Result schema versioning with schemaVersion. ✅
  • Read-only inspection API: GET /api/paradigms, GET /api/paradigms/:key, GET /api/paradigms/metrics, GET /api/paradigms/units. ✅

Done: the registries live in backend/src/config/{units,metrics,paradigms}.js with isKnownMetricKey(...) ready to reject unknown result keys at Step 4. Pending: surfacing paradigm detail pages in the frontend and wiring rejection into result submission.

Exit criteria: every metric has a unit, definition, input list and aggregation behavior.

Step 3 - Scenario: the central experiment definition ✅

Section titled “Step 3 - Scenario: the central experiment definition ✅”

A Scenario is the complete, reusable definition of one experiment, so running a test is just “pick a subject and go”. The domain stays small: Subject (the mouse, kept simple), Paradigm (read-only catalog), Environment (a named paradigm instance - the physical setup), Scenario (the central object), and Test (one run).

A scenario references one or more Environments (N-N), so it can span one or more paradigms; each environment’s paradigm fixes its metrics. It carries no pass/fail criteria - a behavioral result is data, not a verdict.

A Test is Subject + Scenario, run environment by environment (Start → record metric results → Finish). The result is stored per environment (result.environments[envId].metrics), validated against the environment’s paradigm dictionary - the same shape the CV service will push.

  • Redesigned the starter Scenario (POOL | MAZE | STICK | PATH) into a named bundle of environments (+ optional session params). ✅
  • Test.result is structured per-environment JSON; no passed/verdict. ✅
  • Separated signals (raw, CV-side) / metrics (definitions) / metric results (values). ✅
  • Subject stays the simple starter model. ✅

Dropped from the earlier plan: rich Subject, WeightLog, DiseaseModel/Treatment, Study -> Group, a separate Apparatus model. The physical rig is the Environment; calibration stays in Step 5.

  • POST /api/tests/:id/result with X-Service-Key.
  • Idempotency through captureSessionId.
  • Result validation against the active paradigm spec and metric dictionary.
  • cv-service/ skeleton with its own PostgreSQL and /health.
  • Stub result push with fake but valid metrics.
  • MinIO for videos and artifacts.
  • Apparatus geometry editor for circle, rectangle, plus and custom polygon.
  • Zone editor for platform, center, periphery, quadrants, wall annulus and arms.
  • Reference-frame calibration with pixel-to-cm mapping and reprojection error.
  • Fixed apparatus calibration and per-test override.
  • MWM normalization with tank-centered coordinates, raw cm values and normalized distances.
  • Camera adapters: local_usb, uploaded video file, and later phone stream.
  • Detection or segmentation model for mouse localization.
  • ByteTrack or equivalent tracker.
  • OpenCV preprocessing and homography.
  • Per-frame telemetry stays in the CV service.
  • Summary metrics are pushed to Mişko.
Paradigm MVP metrics
MWM Escape latency, path length, swim speed, quadrant time, thigmotaxis, platform crossings for probe trials.
  • Tracking confidence, dropped frame ratio, calibration error, occlusion ratio, out-of-bounds ratio, lighting warning and contrast warning.
  • QC statuses: PASS, WARN, REVIEW_REQUIRED, FAIL.
  • QC is stored alongside the metric results (it qualifies the data, it is not a verdict).
  • Manual review screen with video, overlay, trajectory and metric summary.
  • Study exports filter low-quality runs by default.
  • Scenario dashboards aggregating their tests; compare subject groups (via Subject.groupName).
  • Per-subject history across tests.
  • MWM acquisition curves and probe summaries.
  • Novel object, pole test and treadmill summaries.
  • CSV and JSON exports with metric definitions and QC status.
  • Optional pose-estimation adapter: DeepLabCut, SLEAP or another open source model.
  • Behavior classifiers for rearing, grooming, freezing, risk assessment and head direction.
  • Pose-based event detection where the body centre is not enough (nose-directed novel object exploration, the pole turn from head direction).
  • Multi-animal support after single-animal workflows are stable.
  • CV to Vue live panel through WebSocket or SSE.
  • RTSP and HTTP adapters.
  • Phone getUserMedia push adapter.
  • Live QC warnings.
  • Final license strategy for Mişko and CV service.
  • Docker Compose profile for the full local stack.
  • GHCR image publishing.
  • GitHub Pages docs deploy.
  • Example datasets, demo videos and sample apparatus definitions.
  • No sensor fusion in the core architecture.
  • No RFID, accelerometer, load cell or IR beam dependency.
  • No raw frame telemetry in Mişko PostgreSQL.
  • No editable DB rows for scientific paradigm definitions.
  • No cross-lab multi-tenant deployment in the first architecture.