Architecture

Introduction

Corridor Quest (cq in short) is developed as a client server application.

Server component

The server component executable is called cq-server. It is a cloud native implementation. it has an API first design and the API is RESTful. This means you can run multiple instances of the server component behind a proxy / load balancer. It is also available as a container image so you can run it using Podman for example. It also comes with a helm chart to be able to run it on Kubernetes.

The server component requires a PostgreSQL database. It has been tested with PostGreSQL v18 only currently. The location of the database is define by an environment variable DATABASE_URL which defines all needed information in its string. An example is:

DATABASE_URL=postgresql://postgres:/cq

The API is self documenting using OpenAPI and Swagger UI. the relative url's for the API documentation are as follows:

  • for Swagger UI: /api-docs (for example: https://cq.example.com:3000/api-docs)
  • for the OpenAPI JSON spec (for example: https://cq.example.com:3000/api-docs/openapi.json)

The server accepts either http or https inbound connections as controlled by environment variable REQUIRE_HTTPS. https is strongly advised as passwords are otherwise send in clear text over the wire. https configuration can be in one of three ways:

  1. Direct https with a valid certificate
  2. X-Forwarded-Proto header (common in reverse proxies)
  3. RFC 7239 Forwarded header

Server logging is sent to standard out. Log level is controller by an environment variable LOG_LEVEL. Meaningfull values are INFO and DEBUG.