Understanding the application architecture
Offen Fair Web Analytics is composed of four major parts.
Table of contents
The script
In order to use Offen Fair Web Analytics to collect usage data on a site, the script needs to embedded on each page that is supposed to be contained in the statistics. It is a simple script that will collect and transmit basic pageview data on pageload as well as on pushstate events.
The vault
Offen Fair Web Analytics aims to protect all of the data it is handling from 3rd party scripts that might be running on the same host page as the script. This is why the vault acts as intermediate layer between client side applications like the script and the auditorium, leveraging the protection offered by the Same-Origin-Policy.
The vault is a basic HTML document that is supposed to be loaded in an invisible iframe by any application that wants to use it to interact with the server. It runs a script that is listening for postMessage messages emitted by its host document. It is also able to query for data - either in the local IndexedDB or against the server - and respond to messages if needed. Message origins are checked and responses are limited to messages coming from the same domain, ensuring no data is leaked to 3rd parties.
The vault should be the only interface for both the script and the auditorium to read and update data on the server as it ensures all data exchange is protected. The vault also has two other important responsibilities: it handles all client-side cryptography, ensuring event data is encrypted before leaving the browser, as well as managing the data that is persisted in the local IndexedDB. Handling IndexedDB operations from the vault also ensures it is only accessible to Offen Fair Web Analytics and protected from 3rd party access.
The auditorium
A pure client side application, the auditorium is responsible for displaying usage data to both users and operators. It is also used to manage data and accounts.
This application is only concerned with display logic and performing requests against the vault, all business logic will be a concern of the vault instead. The auditorium should never read or write data from and to sources other than the embedded vault.
The server
The server is a server side application that has two responsibilities: it serves the static assets generated by the script, the vault and the auditorium (in local development these assets are being proxied by nginx though). Also, it exposes a HTTP JSON API these client side scripts can use to create and query event data and manage accounts.