Engine

The engine (@box/backend) is the backend a box runs. It is a thin shell that composes the entitled @withpotter/* packages into one NestJS application running on Fastify, exposes a single OpenAPI document, and runs every package’s migrations on boot.

What the shell provides

• One app, many packages. Each entitled package ships a Nest module; the engine imports them all and serves them under one HTTP server.
• Ports & adapters. Packages depend on each other through DI tokens (ports), not direct imports. The shell binds adapters to those ports — noop defaults out of the box, real implementations when the operator supplies them. See Adapters & ports.
• One OpenAPI document. Every package’s routes are aggregated into Swagger at /docs. See OpenAPI & routes.
• Auto-migrations. On boot the shell globs every package’s bundled migrations and runs each exactly once.

Bootstrap

The engine boots a Fastify-based Nest app with:

• CORS scoped to BOX_CORS_ORIGINS, credentials enabled.
• A global ValidationPipe (transform: true, whitelist: true) so DTOs are validated and stripped.
• Multipart uploads registered with a 100 MB file ceiling.
• Swagger mounted at /docs (UI) and /docs/json (OpenAPI JSON).
• Listening on PORT (default 3001).

Module assembly

Every package is imported through a .forRoot() call that receives the shared authGuard and any adapter bindings the package needs:

ProductModule.forRoot({
  authGuard: AuthGuard,
  mediaCleanup: { provide: MEDIA_CLEANUP, useClass: PlatformMediaCleanupAdapter },
  imports: [PlatformMediaModule],
}),
BookingModule.forRoot({
  authGuard: AuthGuard,
  paymentProvider: { provide: PAYMENT_PROVIDER, useClass: NoopPaymentProviderAdapter },
  // ...
}),

The shell also aggregates every package’s Sequelize models into a single ENGINE_MODELS registry passed to SequelizeModule.forRootAsync().

First-party routes

Beyond the package routes, the shell itself serves:

See OpenAPI & routes for details.

Sections

• OpenAPI & routes — accessing and reading the live API document.
• Adapters & ports — the override model, including payments.
• Configuration — every environment variable the shell reads.