Skip to content

Architecture

Mişko is a Go API with a Vue panel and a PostgreSQL database. Video analysis runs outside the API, in workers that ask for jobs and upload their results.

Layer Technology
Backend Go 1.27 · pgx · sqlc · PostgreSQL 18
Frontend Vue 3 · Vite · Vue Router · Pinia · vue-i18n
Security JWT · bcrypt · role based access control
Storage Google Cloud Storage (private bucket, signed URLs)
Worker Python · PyAV · NumPy · SciPy
Infra Docker · Docker Compose · Nginx · GitHub Actions

The API is a modular monolith. Every domain is its own package under internal/, and each one is split the same way:

internal/<domain>/
├── domain/ pure business rules, no database and no HTTP
├── application/ use cases and the ports they need
└── adapters/
├── http/ routes, request decoding, error mapping
├── postgres/ queries generated by sqlc
├── catalog/ read-only views of the paradigm catalog
└── token/ token issuing and verification

internal/bootstrap is the composition root: it wires the concrete adapters into the use cases and mounts every route. internal/access/domain holds the shared permission kernel, and a use case calls actor.Require(permission) before it touches a store.

The domains follow the study model (see Domain model):

Package Owns
identity, laboratory Users, sign-in, roles, the laboratory singleton
catalog Substances and disease models
subjects Animals and their body weights
experiments Experiments and their lifecycle, groups, regimen items, timepoints, endpoints, allocation and exclusion
dosing Administrations, the daily dosing schedule, induction outcomes
paradigms The versioned paradigm catalog and the metric engine (code only)
environments, protocols Arenas with measurement revisions; test batteries of an experiment
tests Sessions, the animals in them with their arenas, trials, comments
media, calibration Videos (of tests, and assets for trials); calibrations owned by an arena, an animal of a test or a paradigm trial
analysis The analysis service: jobs, workers and capabilities, leases, outputs, metrics, events and QC
subjectanalysis The experiment side of analysis: which job analyses which animal, the orchestrator, review
trials Paradigm trials: a paradigm tried on one video in one arena, outside any experiment
reports, dashboard The read-only study report, CSV export and start-screen counts

Modules do not import each other. Where one needs another at run time, the consumer declares a small interface (a port) in its application package and internal/bootstrap wires an adapter that calls the other module: the analysis service’s port (Submit, Get, Jobs, ByRequester, Results), the media asset port, the calibration port and the environment revision port. Where one refers to another’s rows, for example an allocation to a subject, the database enforces it with foreign keys, and the reporting views in the schema join the tables for the report. The paradigm catalog is a shared kernel that only each module’s adapters/catalog reads.

trials ───────────┐ ┌──► media (source videos)
├──► analysis (port) ─────┤
subjectanalysis ──┘ │ └──► calibration (snapshot)
│ └──► listener: "job succeeded" ──► subjectanalysis
└──► reports, dashboard (views over accepted jobs of animals)

A policy test in tests/architecture enforces the shape: domain and application packages may not import adapters, domain code is limited to a small allowlist of standard library packages, adapters import only their own module, the analysis service never imports the experiment side or trials, and trials never import the experiment side. A layering mistake fails the build rather than waiting for review.

Every list endpoint returns a paginated envelope rather than a bare array:

{ "data": [ ... ], "total": 42, "page": 1, "pageSize": 10 }

page and pageSize are query parameters, and the database applies the paging. On the panel a single DataTable component and the useDataTable composable consume this envelope, so search, paging and sorting behave the same way on every screen.

The camera and computer vision side is not a second service with its own database. It is a worker process that authenticates against this API:

Panel ──► Go API ──► PostgreSQL (records, metrics, events)
│
│ Authorization: Worker <token>
▼
Worker ──► reads the recording and writes its outputs
│ to the bucket with signed URLs
▼
Cloud Storage (original video, analyzed video, trajectory)

The analysis service analyses “this video, with this paradigm version, these parameters and this calibration”. A job is an immutable input snapshot (the source video generation and clip, the resolved parameters, a copy of the calibration with its crop, transform and zones, and an opaque requester: an animal of a test or a paradigm trial) plus its execution state (attempts and lease, outputs, metrics, events, QC). Two modules request jobs: the experiment side submits one per animal of a test when the animal is ready, and paradigm trials submit one per trial video and again on demand with changed thresholds. A worker claims a job with its calibration snapshot, whose crop is the arena’s region of the frame, reads the pinned source video and uploads an analysed video and a misko.trajectory.v1 trajectory. It does not send metrics, and it never learns the animal’s group or treatment. The API verifies every uploaded object against its declared size, checksum and content type, applies the paradigm’s quality rules, and then the Go metric engine computes the metrics and events from the trajectory. That keeps one definition of every measurement inside the API, whatever produced the tracking. A result counts in the study report only after a person accepts it, and only jobs linked to animals of tests can be reviewed: a paradigm trial’s job never reaches review, reports or the dashboard.

Heavy data stays in the bucket: the database holds records, metrics, events and references to objects, never video bytes.

The stack runs with Docker Compose: PostgreSQL, the API, the jobs process that ticks the scheduler (lease expiry, automatic jobs of animals and trials), and Nginx serving the panel. The schema and the first administrator are installed by explicit commands (bootstrap migrate and the one-time bootstrap setup), not on container start. migrate applies numbered SQL migrations in one transaction and records them, and every deploy runs it before starting the new containers. The schema was rebuilt from scratch for the study model; a database installed with the earlier migrations is refused and must be reset. Backend, frontend and worker each have their own path-filtered GitHub Actions pipeline.