Concierge Apps

Concierge is divided in three apps: api, web and workers, embracing the container architecture encouraged by the Hanami framework. This page is intended to explain how the apps work together and the differences in terms of configuration when running Concierge in different environments.

Responsibilities

Just so that things are clear, the api app is responsible for being a Roomorama webhook provider for different suppliers. It is able to accept incoming webhooks from the Roomorama website, translate them to Concierge's expected input format, process the request, serialize a response that is compatible with Roomorama's webhooks and send it back to the caller. This is the core of the Concierge project, and is the reason the project was created.

The workers app does not have any accessible interface - be it a UI or an API. It is a collection of utility classes for performing the synchronisation between supplier-provided properties and Roomorama. It is able to check which host accounts need to be synchronised, queue jobs on SQS for processing and also provide a background worker implementation to pick up those jobs and process them.

Growing from Concierge's goals of providing a system that is reliable even in situations where failures might happen (infra-structure wise or supplier wise), the web application was created. Its fundamental raison d'être is to provide an easily accessible interface through which these errors can be inspected. Oftentimes, things go wrong and it is hard to gather all the information necessary to understand the issue - Concierge's web interface, therefore, aims to solve that shortcoming by displaying data collected by the api and workers applications during its runtime.

Directory Structure

Different Hanami apps are stored under the apps directory, at the root of the project. Depending on the nature of application, different framework features might be needed - for instance, the web application naturally needs assets to display the views, which is not the case for the api application, accessible purely by HTTP endpoints.

Follows the directory structure at the time of writing (Concierge version 0.3.0).

% tree -d apps/
apps/
├── api
│   ├── config
│   │   └── initializers
│   ├── controllers
│   │   ├── atleisure
│   │   ├── jtb
│   │   ├── kigo
│   │   │   └── legacy
│   │   ├── params
│   │   └── poplidays
│   ├── middlewares
│   ├── support
│   └── views
├── web
│   ├── assets
│   │   ├── images
│   │   ├── javascripts
│   │   └── stylesheets
│   ├── config
│   │   └── initializers
│   ├── controllers
│   │   ├── dashboard
│   │   └── external_errors
│   ├── middlewares
│   ├── support
│   ├── templates
│   │   ├── dashboard
│   │   └── external_errors
│   │       └── events
│   └── views
│       ├── dashboard
│       └── external_errors
└── workers
    ├── comparison
    ├── config
    │   └── initializers
    ├── operation_runner
    ├── processor
    ├── queue
    └── suppliers

40 directories

Concierge boot process

When running on API mode, only the files under apps/api will be loaded - similarly, only apps/web is loaded when Concierge is started in Web mode. That guarantees that only required files are loaded and there is no conflict when booting the applications (even though all classes should be namespaced.)

The files under lib are loaded no matter what app is being booted and therefore, files placed under that directory are only utility classes that need to be shared across apps.

The CONCIERGE_APP environment variable

Concierge knows its modus operandi by inspecting the content of the CONCIERGE_APP variable, which must be defined upon boot time. Accepted values for this environment variable are:

• api: Concierge boots on api mode. Only files under apps/api are loaded. The root endpoint of the application is taken by the api app. This is staging/production behaviour of the api app.
• web: Concierge boots on web mode. Only files under apps/web are loaded. The root endpoint of the application is taken by the web app. This is the staging/production behaviour of the web app.
• workers: Concierge boots on workers mode. Only files under apps/workers are loaded. There is no network accessible endpoint. Background workers should be configured (see Workers::Processor::Master) and the cron tasks should be started.
• all: mixed mode. Files under apps/api, apps/web and apps/workers are loaded. No app responds to the root endpoint. The api app is mounted on /api and the web app under /web. This is the behaviour of development/test environments, where it is convenient to have all apps loaded.

Initializers

As depicted in the Directory Structure section earlier, each app has its own config/initializers directory. All files declared there will be loaded when the correspondent application is loaded. Similarly, there is a config/initializers directory at the root of the project. Files included under that directory are always loaded, no matter what Concierge app is being run.

Declarations under the app-specific initializers take precedence over the ones at the root directory.

Environment Variables

Concierge enforces that all required environment variables are properly set at boot time. Applications can declare the environment variables they need in the app-specific apps/#{app}/config/environment_variables.yml file. Similarly, environment variables declared under config/environment_variables.yml are required no matter which app is being loaded.