slotify-backend

Set up

1. Clone repo, there is a submodule so you must use:

git clone --recurse-submodules

2. Install make

3. Install pre-commit:

    pip install pre-commit
    pre-commit install --hook-type pre-push

4. Install the other hooks:

    pre-commit install

This will make sure that golang ci lint is ran before you commit so we don't need to fix errors after pushing.

5. Install Golang (Go is still needed for go generate ./..., if this is a problem we can dockerise)
6. Run the app through:

    make generate # locally runs go and generates files needed, must be run
    make run # runs docker compose up, starts up golang server and db in containers
    make stop # docker compose down, stops the above containers

(See other options in the Makefile)

Project Structure

.
├── api  # API code
├── cmd # Entry point to our API
├── database # Database utilities
├── docs #Docs screenshots
├── generate # Defines go files for oapi-codegen generation (see below)
├── go.mod
├── go.sum
├── integration # Integration tests
├── jwt # jwt utilities package
├── logger # logger utility package
├── Makefile # Defines commands to use for this app (eg. make run)
├── mocks # generated mocks
├── notification # real-time notification service package
├── oapi_codegen_cfg_schema.json # schema for oapi-codegen options (see below)
├── README.md
├── shared # shared repo submodule (containing docker containers and db schema)
├── sqlc # sqlc generated sql queries
├── sqlc.yaml # sqlc config
└── testutil # test utilities

OpenAPI

Our OpenAPI spec can be found at openapi.yaml

oapi-codegen Go lib is used to generate server code based on shared/openapi/openapi.yaml, so things like input validation, registering handlers among other things are automated.

/generate/oapi_codegen_cfg.yaml defines our oapi-codegen config (eg. what Go server to use), to see everything that can be stated in this file see the oapi_codegen_cfg_schema.json

make generate

This will generate API code based on our spec into a file named api/server.gen.go

To view the SwaggerUI, look at the website repo and follow the instructions.

OpenID Microsoft Flow and Slotify API protection

In order to authenticate a user, the OpenID Connect flow is used, this is done through a authorisation code flow.

Slotify's API has its own protection in the form of a JWT access and refresh token. This is stored in the frontend as http-only cookies which are sent with every fetch request.

Notifications

We have real-time notifications set up.

Usage:

    // This is it
    // s is the Server type
    s.NotificationService.SendNotification(...)

How do they work?

Our notification system uses server-side events.

A map of clients is mapped to each user, a client is registered when a client uses the website and makes a call to the /api/events eventstream route. From there, notifications can be sent from server to client in real time.

If a notification is meant for a user who doesn't have a client (ie. not currently using the website, imagine an offline user was added to a slotifyGroup), then on the next login these notifications are fetched from the database and displayed.