Skip to content

Building blocks

This page opens the Ochema box of the context diagram in two steps: the containers that run (C4 level 2), then the modules inside the API (C4 level 3). It is section 5 of the arc42 template.

Every box and arrow below was checked against the repository: the containers against apps/*, Dockerfile and docker-compose.yml, the modules against apps/api/src/modules, and the arrows between modules against their import statements and their NestJS @Module declarations.

flowchart TB
  staff(["<b>Carrier staff,<br/>platform team</b><br/>[Person]"])
  driver(["<b>Driver</b><br/>[Person]"])
  public(["<b>Applicant, driver,<br/>previous employer</b><br/>[Person]"])
  visitor(["<b>Visitor</b><br/>[Person]"])

  subgraph ochema["Ochema [Software system]"]
    web["<b>Office system</b><br/>[Container:<br/>React, Vite]"]
    driverapp["<b>Driver app</b><br/>[Container:<br/>React PWA]"]
    careers["<b>Careers site</b><br/>[Container:<br/>Astro, Node.js]"]
    landing["<b>Landing and<br/>docs sites</b><br/>[Container:<br/>Astro, static]"]
    api["<b>API</b><br/>[Container:<br/>NestJS]"]
    worker["<b>Worker</b><br/>[Container:<br/>NestJS, BullMQ]"]
    db[("<b>Database</b><br/>[Container:<br/>PostgreSQL]")]
    redis[("<b>Queues and<br/>counters</b><br/>[Container:<br/>Redis]")]
  end

  storage[["<b>Object storage</b><br/>[External system]"]]
  providers[["<b>SMS, email and<br/>calendar providers</b><br/>[External systems]"]]

  staff -->|"Uses"| web
  driver -->|"Uses"| driverapp
  public -->|"Uses"| careers
  visitor -->|"Reads"| landing

  web -->|"JSON,<br/>HTTPS"| api
  driverapp -->|"JSON,<br/>HTTPS"| api
  careers -->|"JSON,<br/>HTTPS"| api
  landing -->|"JSON,<br/>HTTPS"| api

  api -->|"SQL"| db
  worker -->|"SQL"| db
  api -->|"Queues<br/>jobs"| redis
  worker -->|"Runs<br/>jobs"| redis
  api -->|"S3<br/>API"| storage
  worker -->|"S3<br/>API"| storage
  worker -->|"Sends,<br/>syncs"| providers
  api <-->|"Webhooks in,<br/>OAuth out"| providers

Legend. Rounded shape: a person. Plain box: a container, with its technology in brackets. Cylinder: a data store that is a container of Ochema. Box with double side borders: a system outside Ochema. Arrow: the direction of the call, labelled with what it carries. The large box is the boundary of the system. The landing site and the documentation site are drawn as one box because they are built into one static output; the table lists them apart.

Container Technology Responsibility Source
Office system React, Vite A single page application with every screen of the ten modules for carrier staff, and the platform panel at /admin for the platform team. Screens are built with Tailwind and the components of packages/ui. English and Spanish. apps/web
Driver app React, Vite, PWA An installable progressive web app whose shell is cached for use without signal. It has sign-in, company selection and the Home, Loads, Documents and Messages screens. The four screens show empty states: the driver features are Planned. apps/driver
Careers site Astro on Node.js The public pages, rendered on the server, with React only where a page has interaction: careers page and job page of each company, application form, short links, interview scheduling, full application, signing, the candidate and driver area, unsubscribe, and the page a previous employer answers on. English and Spanish. apps/careers
Landing site Astro, static The marketing site and the contact form. English only. Its build output carries the documentation site under /docs. apps/landing
Documentation site Astro Starlight, static This documentation. No call to the API. Built before the landing site, which depends on it in turbo.json, and copied into the landing output by apps/landing/scripts/copy-docs.ts. apps/docs
API Node.js, NestJS The only way into the data: REST routes for the front ends, public routes for the careers site, the lead intake API, the webhooks of the providers. Runs on Express, reads and writes with Drizzle, and publishes the OpenAPI document the clients are generated from. apps/api
Worker Node.js, NestJS, BullMQ Everything that does not happen inside a request: delivery of domain events, sending of messages, automations, sequences, broadcasts, reminders, PDF generation, calendar reads and writes, daily compliance routines, exports and maintenance. A NestJS application without HTTP. apps/worker, hosting the jobs modules of apps/api
Database PostgreSQL 18, PostGIS One database for every company. Tables of every module, row level security policies, and the schemas app, gate, staff and search with the functions described in Tenant isolation. The extensions postgis, pg_trgm, btree_gin, btree_gist and unaccent live in the schema extensions. packages/db
Queues and counters Redis BullMQ queues under the prefix <REDIS_KEY_PREFIX>:bull and the counters of the request limits. For the recurring routines the queue is only the trigger: the worker asks the database which companies have work due. docker-compose.yml, service redis
Object storage S3-compatible The bytes of every file. An outside system, listed here because Ochema owns the layout of the bucket: every key starts with tenants/<tenant_id>/. apps/api/src/core/storage

What the arrows mean in practice:

  • The front ends never write an HTTP call by hand. apps/web, apps/driver, apps/careers and apps/landing import the client generated in packages/contracts. A lint rule forbids fetch and XMLHttpRequest in the React apps (packages/config/eslint-react.js).
  • The browser of a visitor never calls the API from the careers site. The careers server does, on behalf of the visitor, and passes the visitor’s address on so that request limits count the visitor.
  • The API and the worker are the same code base. apps/worker has two source files. It starts the WorkerModule that apps/api exports as @ochema/api/worker, so a queue consumer lives next to the module it belongs to.
  • The API does not send messages. It writes the message and queues it; the worker calls the provider (“Sends, syncs” in the diagram, which also covers reading and writing calendars). The providers call the API back through webhooks. The API calls a provider directly in two cases only: the OAuth flow that connects a calendar, and the “Send test email” button of Platform > Integrations.
  • Both processes connect to the database as the same role, ochema_app, which is subject to row level security and has no BYPASSRLS.

The containers are built from five workspace packages. The table lists who depends on what, from each package.json.

Package What it holds Used by
packages/db Drizzle schema, versioned SQL migrations, row level security policies, the transaction context helpers, seeds apps/api (and through it apps/worker)
packages/contracts openapi.json, generated from the API code, and the typed client generated from it apps/web, apps/driver, apps/careers, apps/landing, packages/app-kit. apps/api imports only its SMS segment counter.
packages/ui Design tokens, theme and components: the only source of appearance apps/web, apps/driver, apps/careers, apps/landing, apps/docs, packages/app-kit
packages/app-kit What the two React apps share that has no appearance: request helper, i18n base, router link apps/web, apps/driver
packages/config Shared ESLint, TypeScript and Prettier configuration, with the lint rules that enforce the architecture Every workspace

The API is a modular monolith: one deployable, split into modules with a public interface. apps/api/src has two parts.

  • core/ is the shared kernel. Every module imports it, and it imports no module.
  • modules/ has 14 folders. Ten are the business blocks of the product, named after them. Four more (platform-messaging, platform-signing, platform-automations, platform-mail) are services of the platform that several modules use. They are folders of their own, and import no business module, so that sharing them never closes an import cycle.
%%{init: {"flowchart": {"wrappingWidth": 180}}}%%
flowchart TB
  platform["<b>platform</b><br/>[Component]<br/>Accounts, roles,<br/>Home, panel"]
  attract["<b>attract</b><br/>[Component]<br/>Jobs, careers page,<br/>leads, broadcasts"]
  recruit["<b>recruit</b><br/>[Component]<br/>Candidates, pipeline,<br/>scheduling, offers"]
  people["<b>people</b><br/>[Component]<br/>Directory, terminals"]
  compliance["<b>compliance</b><br/>[Component]<br/>Driver files, rules,<br/>screenings"]
  fleet["<b>fleet</b><br/>[Component]<br/>Vehicles"]
  operations["<b>operations</b><br/>[Component]<br/>Customers, locations"]
  signing["<b>platform-signing</b><br/>[Component]<br/>Envelopes, PDFs"]
  messaging["<b>platform-messaging</b><br/>[Component]<br/>Single send path,<br/>provider adapters"]
  automations["<b>platform-automations</b><br/>[Component]<br/>Rule engine"]
  mail["<b>platform-mail</b><br/>[Component]<br/>Account email queue"]
  stubs["<b>driver, portals, finance</b><br/>[3 components]<br/>Access check only"]

  platform --> attract
  platform --> recruit
  platform --> people
  platform --> compliance
  platform --> fleet
  platform --> operations
  platform --> messaging
  platform --> mail
  attract --> recruit
  attract --> messaging
  recruit --> people
  recruit --> compliance
  recruit --> signing
  recruit --> messaging
  recruit --> automations
  recruit --> mail
  people --> compliance
  compliance --> signing
  compliance --> messaging
  signing --> messaging

Legend. Box: a component, which is one folder of apps/api/src/modules and one or more NestJS modules. Arrow: “imports from the public interface of”. An arrow is drawn when a file of the first module imports a value from the index.ts of the second. Not drawn: every module imports core, and compliance imports type definitions from platform-automations.

The graph has no cycle. Three properties keep it that way:

  • One door per module. A module imports another only through its index.ts. The lint rule ochema-api/module-boundary (apps/api/eslint-module-boundary.js) reports any import of an internal file of another module.
  • No cycles at load time. apps/api/test/module-cycles.test.ts starts the whole API with each of six entry files imported first, which fails if a cycle of imports exists.
  • Inversion where the natural direction would close a cycle. The automation engine belongs to the platform, yet Recruit and Compliance own the triggers and actions. They register them in AutomationRegistry; the engine never imports them. Message links and attachments (MessageLinkResolvers, MessageAttachmentResolvers), reactions to a signature (SigningListeners) and access to a file (FileOwnerResolvers) work the same way.

The first table is the outside of each module: the path prefixes of its routes in the OpenAPI document, and what its index.ts exports for the other modules of the API.

Module Routes Public interface for other modules
attract (block A) /attract, /public/careers, /public/links The job counts for Home.
recruit (block B) /recruit, /public/applications, /public/full-application, /public/scheduling, /public/interview-calendars, /public/v1/leads LeadIntakeService, the one way a lead enters. ApplicationMoveService, the one way an application changes stage or status. CandidateMergeService, the scheduling service, smart list audiences, OfferSender, counts for Home.
compliance (block C) /compliance, /public/portal, /public/safety-history ComplianceEngine, the one way a driver file changes. Onboarding. DrugAlcoholIntake, which writes to the drug and alcohol file without reading a result. Portal links and the automation definitions of Compliance.
people (block D) /people createHiredPerson, linkHiredPerson and undoHiredPerson: what hiring does to the directory. Counts for Home.
fleet (block E) /fleet The vehicle count for Home.
operations (block F) /operations The customer and location counts for Home.
driver (block G), portals (block H), finance (block I) /driver/access, /portals/access, /finance/access Nothing.
platform (block J) /auth, /platform, /home, /search, /health, /public/leads, /admin Nothing.
platform-messaging /platform/messaging-settings, /public/unsubscribe, the provider webhooks under /public/v1/webhooks MessageSendService, the one way a message leaves. InboundMessageService, MessageStatusService, the link and attachment resolvers, template rendering and the provider interfaces.
platform-signing /signing, /public/signing SigningService, SigningListeners and the PDF generator.
platform-automations None of its own: Recruit serves the automation screens. AutomationEngine, AutomationRegistry, AutomationRulesService and the definition types.
platform-mail None. PlatformJobs, the producer of the account email queue.

The second table is the inside: what each module runs in the worker process, and which modules it imports.

Module In the worker Imports
attract Broadcasts: starts the scheduled ones and hands the recipients to the send path. recruit, platform-messaging
recruit Lead scoring, candidate import, overdue tasks, automation actions, sequence steps, interview reminders, abandoned application reminders, full application links, offer expiry, scorecard tasks. compliance, people, platform-messaging, platform-signing, platform-automations, platform-mail
compliance The daily engine routine, onboarding at hire, expiration notices, safety history reminders and deadlines, audit exports and their cleanup. platform-messaging, platform-signing
people Nothing. compliance
fleet, operations, driver, portals, finance Nothing. None
platform Account email delivery, hourly and daily maintenance, calendar reads and writes. recruit, attract, compliance, people, fleet, operations, platform-messaging, platform-mail
platform-messaging The send queue, the provider adapters and simulators, the daily usage check. None
platform-signing Document PDFs and final PDFs, signer emails, expired envelopes. platform-messaging
platform-automations The automations queue, mounted by Recruit with its triggers and actions. None
platform-mail Nothing of its own: Platform consumes the queue. None

platform imports six business modules for three reasons: Home shows one count from each (jobsCounts, activeCandidatesCount and the like), removing a user must first release that user’s candidates, rules and interviews in Recruit, and the calendar adapters implement the calendar interface that the scheduling service of Recruit defines.

driver, portals and finance exist so that the module switch and the permission of each block already work end to end. Each has a single route that answers whether the module is on and the caller may open it.

Part What it gives every module
config The validated configuration. A missing or malformed setting stops the start with the name of the variable.
database, http The connection pool and the request pipeline: every authenticated request runs in one transaction whose first statement sets the user and the company. A write route that records no audit row fails and rolls back.
auth Session services for company users and for the platform team, the guards (cross-site request, session, module switch, permission) and the permission catalog.
errors, openapi, validation The error catalog and the single error body, the OpenAPI helpers, shared field validation such as phone numbers in E.164.
audit The one writer of the audit log.
events Domain events: the transactional outbox, the typed catalog, the dispatcher and the registry of consumers, and the discovery of companies with work due. See Background work.
storage The one path of a document: receive, read, authorize by owner. Serves GET /files/<id>. Also the object storage adapter, which three modules use directly for objects that are not documents: a careers page logo, an import spreadsheet and an audit export. See Files and vaults.
sensitive Encryption, masking and logged reveal of Social Security number, date of birth and license number, and the filter that keeps them out of the log. See Sensitive data.
registers The shared pattern of a register: list with search, filters, sorting and cursor pagination, and writes with audit.
redis, rate-limit, mail The Redis client, the request limiter and the transport of account email.

Every route of every module runs behind the same pipeline, declared once in apps/api/src/app.module.ts. A module adds routes and services; it does not add its own authentication, transaction handling or error format.

%%{init: {"flowchart": {"wrappingWidth": 170}}}%%
flowchart LR
  guards["<b>Guards, in order</b><br/>1. Cross-site check<br/>2. Company session<br/>3. Panel session<br/>4. Module switch<br/>5. Permission"]
  tx["<b>Transaction</b><br/>Opens it, sets user<br/>and company"]
  validation["<b>Validation</b><br/>Body, query,<br/>path schemas"]
  route["<b>Module route</b><br/>and services"]
  finish["<b>Audit check</b><br/>then commit"]

  guards --> tx --> validation --> route --> finish

Legend. A flowchart, not a C4 view: boxes are the steps a request with a session goes through, left to right. A refusal at any step, or an error thrown by a route, leaves through one error filter, which answers with the single error body of the API. A write that recorded no audit row fails the audit check and the transaction rolls back.

At start, RouteBoundaryCheck stops the API if a route is marked the wrong way between company and platform panel. A route without a session (a public page, a webhook, a link token) skips the session steps and opens its own transaction through a gate function, as described in Tenant isolation.