Skip to content

0002. React and NestJS with a modular Domain-Driven Design

  • Status: Accepted
  • Date: 2026-10-01

Context

BizOS spans many business areas (identity, tenancy, CRM, contracts, tasks, billing, AI assistant) and is built by a small team where each person owns an area. We need a structure that keeps areas independent, lets one person deliver a capability end to end, and uses one language across the stack.

Options considered

  1. Layered architecture (controllers, services, repositories at the top level): simple to start, but business areas mix and grow coupled.
  2. Microservices per area: strong isolation, but too much operational cost for the team size and stage.
  3. Modular monolith with Domain-Driven Design: modules as bounded contexts, features as vertical slices inside them, deployed as one API and one worker.

For frameworks, React and NestJS were chosen over alternatives because both use TypeScript, have large ecosystems, and NestJS's module system maps directly onto DDD modules.

Decision

  • Organise code by Domain-Driven Design in two levels: modules (level 1, bounded contexts) containing features (level 2, vertical slices).
  • Build the frontend with React and the backend with NestJS.
  • The detailed structure and rules are in STACK.md.

Consequences

  • Each module has one owner and a clear public API, so work in parallel rarely collides.
  • A module can be extracted into a separate service later if needed, because it already talks to others only through its public API and events.
  • Boundaries need discipline and lint enforcement; without them the monolith decays into a layered tangle.
  • One language (TypeScript) across frontend, backend, and shared packages lets API types be shared and generated.