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.
Level 2: containers
Section titled “Level 2: containers”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/careersandapps/landingimport the client generated inpackages/contracts. A lint rule forbidsfetchandXMLHttpRequestin 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/workerhas two source files. It starts theWorkerModulethatapps/apiexports 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 noBYPASSRLS.
Shared packages
Section titled “Shared packages”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 |
Level 3: components of the API
Section titled “Level 3: components of the API”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 ruleochema-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.tsstarts 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.
What each module exposes
Section titled “What each module exposes”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.
Inside core
Section titled “Inside core”| 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. |
The request pipeline
Section titled “The request pipeline”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.
Related
Section titled “Related”- Solution strategy: why the blocks are cut this way.
- Deployment view: where each container runs.
- API routes and Database tables: the generated reference, by module.
- ADR-0001: modular monolith. ADR-0006: worker, queues and work discovery by company.