Creating services

How to configure an Architect service

Getting started Reference Docs

Architect services all follow the same standard blueprint so that they can more easily communicate with one another. This blueprint is quite simple, and is derived from familiar patterns already found in most package managers and many cloud-native tools to-date.

Configuration file

The Architect configuration file, architect.json, houses all the core settings needed for your service to operate effectively. These settings range from discoverability details, like the name and description of your service, through initialization requirements like what language the service uses and what other services yours intends to make calls to.

{
  "name": "my-service",
  "version": "0.1.0",
  "description": "Example service",
  "keywords": [
    "architect",
    "example"
  ],
  "author": [
    "David Thor"
  ],
  "license": "ISC",
  "dependencies": {
    "movie-service": "^1.1.0",
    "fraud-service": "file:../fraud-service/"
  },
  "proto": "service.proto",
  "main": "index.js",
  "language": "javascript"
}

The configuration files are designed to be simple, but also include a variety of optional features that can be used to properly define the scope and requirements of even the most complex services. For a full set of options available in the architect.json file, check out the reference docs.

Proto files & GRPC

Architect defines and exposes services using Protocol Buffers and GRPC which already provides sophisticated RPC transport mechanics for all major cloud languages. By combining the scope of Architect’s service definition with GRPCs, Architect is able to enrich GRPC clients at deploy time with the location of existing or newly generated peer services.

Each service that intends to be consumed by peers includes a .proto file with exactly one service defined. Architect automatically maps the functions defined in this service to those found in the main file of the service making it easier than ever to expose new endpoints to be consumed. There are no constraints on how .proto files can be constructed other than that there must be exactly one defined service.

syntax = "proto3";

message RecommendationRequest {
  string user_id = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

message RecommendationResponse {
  // ...
}

service MovieService {
  rpc RecommendationsByUserId (RecommendationRequest) returns (RecommendationResponse) {}
}

Main file

The main file is the first entrypoint to your service, and is where all of your application logic is first initialized. In order to allow Architect to inject environment-enriched dependency stubs, which are used for connecting to dependencies, Architect requires that these main files be constructed in a consistent and predictable manner. Since these clients are specific to the language being used for the service, the structure of main files varies slightly based on the language being used.

Supported languages

  • Node
  • Python
  • Java (coming soon)
  • Ruby (coming soon)
  • C++ (coming soon)
  • Go (coming soon)

Don’t see your favorite language supported? We’re happy to have contributors help us enroll new languages. To learn more, check out our documentation on launchers - the component of the framework responsible for generating and injecting dependency stubs into applications.