Architecture
There are four main servers: the Frontend server, the API, the OAuth server and an image server. Next to that there is an admin panel which allows for managing all the servers & creating new websites.
The Frontend server is a CMS, that can manage multiple sites. These sites consist of OpenStad widgets that contain specific OpenStad functionality, and generic content. The idea here is that the generic content could be created in any CMS, and the OpenStad widgets handle the specific data through an API. This setup is currently being developed and already available for the Choices Guide and IdeasOnMap widgets. Other widgets, for now, still require the OpenStad Frontend server.
The Frontend automatically creates ApostropheCMS express servers for every domain that is found and validated through the API. When kubernetes is used this allows for autogenerated SSL certificates and automated nginx host creating, for non Kubernetes environments this can be done with wildcard domain settings.
Standard Page Request Flow
1.1 A standard request comes into the frontend, then the frontend server checks if the domain is known in it's memory.
2.1 If no then it will make a call to the API to see if the domain exists in the application.
2.2 If no configuration for that domain is found a 404 page is served.
2.3 If the domain is known the Frontend server gets the configuration returned for the site, checks if the mongob database exists and continues.
3.1 It makes a call to the API to see if user is logged in and then serves the request domain and page.
NodeJS servers
Frontend server: ApostropheCMS
The frontend is built with the ApostropheCMS. ApostropheCMS allows for highly flexible pages. Enabling the UX & designers to build complete websites from the ground up. Laying the foundation for a flexible system that allows for anything from simple voting websites to complex participatory budgeting websites.
On top of the core of ApostropheCMS we have integrated and developed the Openstad (open city) functionality of submitting ideas, voting, participatory budgeting, arguments and more.
The frontend CMS is developed in such a way that it can run multiple sites on one server.
Installation instructions are found in the readme. MongoDB & Node.js are required. ApostropheCMS uses MongoDB for saving it's page data.
https://github.com/openstad/openstad-frontend
Openstad API
The Openstad API is a REST Api that returns JSON.
When the Frontend server gets a visitor it queries the API to get the config needed for the domain visited. Therefore the frontend server can’t run without the API server.
Check the readme for installation.
Make sure the correct environment values are in the .env file of the frontend the API and SITE_API_KEY are required. The SITE_API_KEY is set in the config/local.json file.
https://github.com/openstad/openstad-api
OAuth Server
The OAuth server is required for authenticating & voting users. Oauth server has a role and right system per client. One frontend site can have multiple clients per site. The auth server currently supports the following authentication types: unique code, e-mail with loginlink (not password), anonymous and SMS.
See the readme for installation.
Make sure the correct config values are set in the config/local.json. Every site has it’s own OAuth client. The public clientId and clientSecret should be site in the API sites table in the config.
https://github.com/openstad/openstad-oauth2-server
Image server
We run a nodejs image server that allows for easy uploading and resizing.
This is mainly used when uploading and saving images for submitting an idea by external users. Installation instructions found in readme. Set corresponding values in the .env of the fronted server. https://github.com/openstad/openstad-image-server
Admin panel
The admin panel is an interface for managing the OAuth, frontend & API. All the server run without the admin panel, but it makes it a lot easier to manage and create sites. The panel allows for creating new sites by copying existing sites, managing users, voting codes, voting setting and more.
https://github.com/openstad/openstad-management-panel
Databases & Data management
Openstad uses Mysql (or MariaDB) and Mongodb. Mysql is used by the auth, image and api for managing it's data.
ApostropheCMS uses MongoBD for the content of it's site.
This means user submitted data, like argument, goes to the Openstad REST API which saves it in mysql and exposes it through it's JSON REST Api. The less structured content of the website, like layout info,image, text, video's used for structuring the webpages and managed by the moderators is save in MongoDB by ApostropheCMS.
Frontend Frameworks
The frontend application is managed by ApostropheCMS, but to prevent confusion ApostropheCMS is not the frontend framework we use.
For new JS applications React.js is used. We load it into the frontend via a CDN, for instance via the JS delivery CDN. Often it's wrapped in an ApostropheCMS module which allows for the benefits of easy management of configuration and loading into every application.
JQuery is used by ApostopheCMS 2. And there are some old jQuery scripts from the openstad code base, the important ones, like voting will be moved to react.js in the future. Simple site enhancements, like alerts, will stay in jQuery for now.
Last updated
