Reference and guidelines for contributing to Architect

Architect has chosen to open-source all the tools needed to support local development of services as well as the enrollment of new languages. In doing so, we hope to harbor a thriving community of developers who wish to collaborate more effectively with a common service blueprint. It is only through shared standards that developers are able to adopt common infrastructure practices and uniformly renew focus on what makes their own projects and services unique.

Command-line interface

The command-line interface Architect maintains is designed to enable developers to start complex applications in local or private environments, thus making it easier to debug and test integrations with peer services. By traversing the relationships between services indicated by their configuration files, the CLI is able to determine the order in which services need to be started and executing the correct launcher for the services language.

Though our team maintains and actively contributes to this CLI, the code used by the CLI only starts a single process as-needed on the host machine calling the start command. Creating production service clusters and deploying to a variety of different cloud environments is accomplished using the deployment engine in our Service Hub which does not share code with the CLI.

View Repository


A launcher is a script designed to initialize a service and inject enriched client stubs to be used to make calls to dependencies. Launchers exist for each language supported by Architect and define opinionated expectations for how the main file for services in said language need to be structured. With a reliable expectation of consistent main file structures, the launchers can inject enriched dependency stubs in the correct order to be used by the running service.

Unlike the CLI, launchers are on the critical path for deployments that use our service hub, and represent the only code other than GRPC stubs that Architect injects into running applications. For this reason, it was crucial that we design our business to allow these launchers to be open-sourced so as to provide full transparency into the code that might be introduced to the running processes of services.

In order for the CLI and Architect Hub to start services using launchers, the launchers must all follow the same standards for how they are executed and how they receive parameters. These launchers are written in the language they are designed to support, but must be exposed as executables with the following parameters:

Input arguments

  • --service_path, -s – Local path to the directory containing the service
  • --target_port, -p – Port to expose the process on

Dependency locations

In order to enrich dependency stubs with the location of each dependency, the locations need to be passed into the launcher and parsed accordingly. Launchers accept dependency locations via environment variables that follow a standard naming convention: ARCHITECT_<DEPENDENCY_NAME>, where “" is the name of a dependency a service depends on.

NOTE: All hyphens are replaced with underscores in the environment parameter keys

The contents of each of these environment parameters is a json encoded payload matching the following object structure:

  "host": "",
  "port": "8080",
  "service_path": "/path/to/dependency"

With the above details provided for each dependency, launchers are able to enrich static GRPC stubs with the location of these peer services dynamically and enable a service to reach them without any code modifications.