Project Overview

To stretch the home-base-building metaphor to its limit, HQ.io organizes itself around components called "bricks".

In order to distinguish a brick from a regular software component, the following characteristics must be present:

  • A brick must have at least one UI.

  • A brick must provide a way to transform data into execution.

  • If there is no readily available data, a brick must provide a way to transform a domain specific language (DSL) into data.

  • A brick must include internal logging.

  • A brick must include internal metrics.

  • A brick must self-document it's public API, including any external data, at runtime.

  • A brick must guarantee backwards-compatibility and forwards-compatibility, in perpetuity.

By enforcing these requirements, and no others, we reap the following benefits:

  • A brick is creatable in any programming language or environment.

  • A brick can be used inside HQ.io, even if it is not an HQ.io brick.

  • An HQ.io brick can be used by any other system, even if it is outside of HQ.io.

  • A brick is never forbidden from changing.

  • A future brick can always replace an historical brick.

  • The upgrade path for bricks in any environment is well-known and verifiable at all times.

Looking at the required characteristics of a brick, it appears to be a tall order of guarantees, with high complexity.

In the following chapters, we will cover each characteristic, using one or more HQ.io components, which can be utilized to make HQ.io bricks, as well as help externally developed bricks meet the criteria.

From now on, HQ.io components that are not "bricks" in the definition above, but help facilitate brick building, are called "iron bricks". The bricks that fully meet the criteria for brickhood are called "gold bricks".