Introduction
welcome to the biotrack developer docs! this gives information on ways to hack biotrack, architectural decisions, API, etc..
API
If you're looking for a more convenient way to access the API, see the bindings.
sequenceDiagram
Card Scanner->>Server: Join <id>
Server->>Game: Client requested join
Game->>Server: Acknowledge
Server->>Card Scanner: Notify Game Start
Game->>Server: Finish Game
Server->>Card Scanner: Notify Finish Game
GET /game/<id>/queue
Stream of player join events for a game. Returns a stream of JSON objects,
each with a player and time field.
GET /game/<id>/queue/all
Returns a list of all join events for a game. Useful if your client doesn't support streaming.
POST /game/<id>/join
Join a game with a player uuid.
This does not guarantee that the player joins the game;
rather, the player sends a request to join.
GET /game/<id>/session
Returns a game's active session, if any.
POST /game/<id>/ack
Acknowledge a join event. Requires a list of joinRequest uuids to acknowledge.
Returns a session id.
POST /game/<id>/finish
Finish a session with a score and data as a String.
If continue is true, a score block will still be created,
but the session will not be marked as finished.
POST /player/<id>/create
Create a player with a name.
Structure
There are a few different folders and files going on around here. Let's break them down:
There exists two different SvelteKit apps, one in apps/website,
which acts as the main dashboard for biotrack, and a testing playground
located in apps/carnival, which allows one to test the different features of biotrack
without physical peripherals.
There is this book itself, which is a mdBook,
located at /book.
In crates exists two embedded projects: reader, which acts as a Serial peripheral
for NFC card scanning and writing, and scanner, which acts
as a game scanner to allow players to physically join games.
Security
biotrack employs a variety of different security tactics, but here are some of the decisions that were made in the design of the system.
Officers
Officers are users that are allowed to non-destructively interact with the biotrack dashboard. They can manage relatively any aspect of the database, as long as it doesn't delete any information, as the project is aimed in data analysis - it would be a shame to lose any data.
Officers have two tiers:
- Regular, where they can add and manage players, and manage queuing and sessions for games.
- Admins, who can manage and create other officers, and create and archive games.
Officers are able to log in through the dashboard, and all passwords are hashed and salted using pbkdf2.
Game Tokens
Game tokens are used to authenticate a game to the biotrack server. They are generated by the server and are used to authenticate all API requests.
Orchestrator
With the current model, there would be no way to log into the system on a fresh database. Thus,
if you are on the local computer (i.e. you can access the site via localhost), you are allowed
to manage administraive officers and create new officers, giving you access of the site from other computers.
Orchestrator is a tool on https://localhost:5000/orchestrator that allows
the host to manage all officers (editing, archiving, demoting) and create new officers.
To limit power of orchestrator, to manage games, the orchestrator must create an officer account to control the games. This is to prevent the orchestrator from being a single point of attack.
https
biotrack uses https to support various browser-unsafe chromium only APIs, like
the WebNFC API and
the WebUSB API.
These APIs are only available in secure contexts, which means that the
connection must be encrypted with https.
However, since this is also a local website (not hosted on the internet), the certificates biotrack generates are self-signed, and thus not verified by a certificate authority.
Certificate authorities are usually present to 'verify' the legitimacy of a certificate, and are used to prevent man-in-the-middle attacks. Thus, browsers will report this page as unsafe, as it is essentially acting like how a true malicious connection would act; by faking an HTTPS certificate, this could be some form of the aforementioned MitM attack.
However, this page is not harmful, and the connection is still encrypted from bad actors. If you are using biotrack on a local network, you can safely ignore the warning, unless you are worried about a compromised host network.
If you are worried about a compromised host network, you can manually go to the host computer and verify the certificate fingerprint. The fingerprint is displayed in the browser's developer console, and can be compared to the fingerprint of the host computer.
Bindings
To connect your games to biotrack, you will need to use the biotrack HTTP API.
However, many games end up using the same language. Thus, we provide
bindings for the following languages:
If you would like to contribute bindings for another language, please see the contributing page, and open an issue or pull request on the biotrack repository
C# Bindings
C# binding documentation, SDK, and examples are located at: @GitHub: CoasterFan5/biotrack-unity
Contributing
To contribute, the following tools are recommended:
- Node.js v20+
- npm, which should come with Node.js
- Git
- pnpm, which you can install with npm:
npm install -g pnpm
If you are unfamiliar with git, use a git client such as GitHub Desktop or GitKraken.
To get started, clone the repository and install the dependencies:
git clone https://github.com/LeoDog896/biotrack
cd biotrack
pnpm install
Database
To set up the database, run
npx prisma generate
npx prisma migrate dev
This sets up a SQLite database in the prisma directory.
Whenever you make changes to prisma/schema.prisma, run
npx prisma migrate dev
To reset the database, run
npx prisma migrate reset
npx prisma migrate dev
Development
To start the server, run
pnpm run dev
This will require setting up the database, as well as an .env file
you can get by copying .env.example to .env and filling in the
values.
Testing
To run the tests, run
pnpm test