BrewOS
back to the documentation home page

Technical system description

BrewOS is a PHP/MariaDB application operated on Linux servers. BrewOS is responsible for the system's technical design and development.

The software code makes use of various open-source projects under the licence terms they define, such as:

In addition, the implementation makes use of the following HTML/JavaScript projects and resources:

Key features of the technical implementation

The software architecture is based on the MVC pattern.

The software and its data model are designed for simultaneous use by several separate organisations. Data is stored in shared database tables, and every item of data is tied to the account it belongs to. Every request checks that the user has a role on the account in question.

The database makes extensive use of foreign keys to ensure database integrity. In addition, the software carries out changes as database transactions, within which any error automatically undoes the whole change (rollback).

The user interface is available in Finnish, Swedish and English. In addition there are two looks: the new look, which is everyone's default, and the old look. The user's choice of language and look is stored in a browser cookie and, for a signed-in user, also in their user details.

Sign-in and sessions

  • Passwords are not stored in plain text but as salted hashes.
  • A user can enable a time-based one-time code (TOTP, RFC 6238) as a second sign-in factor. See Strong authentication.
  • The session is kept in a browser session cookie. When signing in, the user can choose Remember me in this browser, in which case a signed sign-in cookie is stored in the browser, valid for 14 days from last use. Changing the password invalidates previously issued sign-in cookies.
  • Password guessing is slowed down: once 5 sign-ins have failed within 15 minutes with the same email address from the same IP address, further attempts are not processed until the oldest failure expires.
  • Password reset and user invitations work with single-use email links that expire in 24 hours.
  • Forms use single-use tokens that prevent the same form from being processed twice.

AI interface (MCP) and OAuth

BrewOS offers a Model Context Protocol (MCP) interface at /mcp. The interface is connected to with OAuth 2.1 authorisation:

  • the server publishes OAuth metadata (/.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource) and supports dynamic client registration
  • PKCE (S256) is mandatory
  • the access token is valid for one hour and is renewed with a rotating refresh token, whose validity ends at the latest 60 days after authorisation
  • tokens are stored in the database only as hashes
  • an authorisation is tied to one account and works with the permissions of the authorising user, which are checked on every call; an authorisation can also be given read-only access
  • the number of calls is limited to 120 calls per minute per authorisation
  • calls that change data are recorded in the account's event log.

Webshop API

A company's own webshop can connect to BrewOS through the webshop API at /rest/webshop/v1. Webshops and their API keys are created on the page Settings > Webshops:

  • each webshop has its own API key, which gives access only to the account's own data and only through the webshop API; the key is stored in the database only as a hash
  • a webshop can have two valid keys at a time, so that the key can be changed without a break
  • the number of calls is limited to 120 calls per minute per key.

Integrations

BrewOS uses the following external interfaces. See Integrations for details.

  • Invoicing and financial management: Maventa (e-invoices), ProCountor, Netvisor, Fennoa and Netbaron
  • The Tax Administration's VeroAPI: sending excise duty returns with a Suomi.fi authorisation
  • Valvira's alcohol trade register Allu: sending delivery and packaging reports, and Valvira's open alcohol licence data for checking outlets and licences. See Valvira.
  • The Finnish Patent and Registration Office's open YTJ data: a company's name and address by Business ID
  • Bisnode: checking a customer company's credit rating

Operations

The system runs in Cloud City's data centre in Finland.

Backups are based on keeping persistent data, including the files users save, in the database. The database is backed up automatically once a day.

Software development quality

The software is maintained in Git version control.

Automated unit tests (PHPUnit) have been written for the software.

Page last updated 23 Oct 2026 11:24