/api is a source folder for three independent services:

  • API — REST API, entry file is /api/src/app.ts
  • Migrator — small utility that runs MongoDB migrations, entry file is /api/src/migrator.ts
  • Scheduler — standalone service, that runs background jobs, entry file is /api/src/scheduler.ts

​
What is resource?

From the outside world, the resource is a set of REST API endpoints that allow managing a particular business entity (e.x. user). Inside, the resource includes methods to work with the database, business logic, database data, request validation, events and event handlers. Most of the time, a resource has 1 on 1 mapping to the database entity. The resource describes how you can work with any given entity. E.x. User API needs to create new users, edit an existing user, list all users.

​
Resource components

A resource represents on REST endpoint and most of the time one database table or collection. The resource usually consists of the following parts:

  • API actions. Each action consists of three things: the handler, validator, and route.
  • A data service. Typically this service is used to access databases. For simplicity, we mix the data access layer with the domain operations associated with a given entity.
  • Event handlers. Event handlers include any updates that come as a reaction to what happens outside the boundaries of any given entity.
  • Workflows. They are essentially updates that require multiple resources to work together. E.x. User Signup is usually a workflow, as it requires to a) create user b) create company 3) create authentication token.
  • Data schema. We use Zod to define database schemas and validate them in runtime. (we’ve used Joi in the past).
  • Type definitions. If typescript is used for the project.

The data schemas and type definitions can be found in the packages folder. Check out the “Package sharing” section for more information on data sharing.

​
Example stucture

Here is the resource structure example:

/resource
  /actions
    get.ts
    create.ts
    ...
  index.ts
  resource.service.ts
  resource.routes.ts
ArchitectureAPI limitations