Bringing the onboarding engine together

The point of this series is not to use every DDD pattern.

The point is to make better architecture decisions in a domain where mistakes are expensive: enterprise onboarding for a shared-schema SaaS product.

Northstar Health Group gave us a realistic pressure test. One global customer has regional compliance boundaries, operational tenants, Entra ID federation, commercial quotas, regional data-plane provisioning, and isolation risk. That is enough complexity to justify careful modeling, but not enough to justify turning the whole system into a pattern museum.

DDD patterns should line up with business risk

Where the code lives

The series does not require microservices.

A good first implementation can be a modular monolith:

• one deployable web application for HTTP/admin/API requests;
• one worker process running the outbox dispatcher and onboarding saga handlers;
• one shared application database with tenant tables, aggregate snapshots, and an outbox table;
• internal modules for Onboarding, Billing, IAM, Provisioning, and the Entra/AD anti-corruption layer;
• public module APIs and import rules that prevent one context from reaching into another context’s internals.

One deployment can still have hard domain boundaries

That shape is often the right place to start. It keeps local development, transactions, observability, and refactoring simple while the domain language is still evolving.

The worker is not a separate domain. It is another runtime entry point into the same application model. HTTP handlers accept requests. Workers react to durable facts. Both should call application services and domain objects through the same boundaries.

When topology matters

Deployment topology matters when it changes ownership, reliability, or operational risk. It matters less when it is only a diagram preference.

DDD helps either way. In a monolith, it gives you module boundaries, public contracts, and language ownership. In a distributed system, it tells you which service contracts are meaningful and which integrations need anti-corruption layers.

Do not split services because the diagram has boxes. Split when the context boundary already exists in the business and the operational cost is worth paying.

The architecture in one pass

1. Start with business language. Separate global organization, regional division, tenant, contract, residency policy, and identity readiness.
2. Draw context boundaries. Onboarding owns lifecycle readiness. Billing owns commercial allocation. IAM owns Entra/SAML federation. Platform owns regional data-plane provisioning.
3. Protect invariants in aggregates. TenantConfiguration decides whether a configuration change is valid after the application layer loads contract, residency, and lifecycle facts.
4. Coordinate time with events and sagas. The outbox makes state changes publishable. The saga handles long-running work, retries, blocked states, and compensation.
5. Make tenant isolation a system property. Repositories, execution context, query filters, database constraints, and audit logs work together.

Each move should answer a business question. If it does not, skip it.

What belongs where

That separation is what keeps DDD pragmatic. The aggregate does not fetch data. The controller does not decide contract policy. The saga does not become a god object. The repository does not hide business rules.

A realistic request path

Here is the final shape for a Northstar seat allocation request:

1. The HTTP adapter validates request shape and parses command fields.
2. The application service loads TenantConfiguration and EnterpriseContract.
3. The aggregate evaluates allocateSeats(requested, contract).
4. Domain errors return as domain errors, not HTTP exceptions.
5. The adapter maps domain errors to HTTP problem responses.
6. On success, the repository saves the new tenant configuration.
7. The same transaction writes an outbox event.
8. A dispatcher publishes the event.
9. The onboarding saga advances or blocks the workflow.
10. Tenant-scoped reads and writes run through context-aware repositories.

There is no single magic layer. The design works because each layer has a narrow job.

Where teams overuse DDD

Do not create aggregates for static lookup tables.

Do not wrap every string in a value object before the language is stable.

Do not introduce a saga for work that completes inside one local transaction.

Do not split bounded contexts by database table or folder name.

Do not use repositories as a blanket excuse to hide every query.

DDD is most useful where the business language is subtle, the invariants matter, and the cost of getting the model wrong is high. For simple CRUD, use simple CRUD.

What to test

Test the places where the design carries risk:

• context mapping tests that prevent illegal imports;
• aggregate tests for quota, residency, lifecycle, and security invariants;
• adapter tests that map domain errors to HTTP responses;
• saga tests for retryable failure, blocked states, and compensation;
• repository/infrastructure tests proving tenant filters are injected;
• migration tests for tenant-scoped indexes and foreign keys.

The tests should not all mention Northstar. Northstar is the teaching scenario. The tests should name reusable business rules.

Final checklist

Before applying DDD to an enterprise workflow, ask:

1. What business language is currently ambiguous?
2. Which ambiguity has caused or could cause real harm?
3. Which teams own the concepts involved?
4. Which invariants must be protected before persistence?
5. Which decisions require facts loaded from other stores or contexts?
6. Which workflow steps can fail after the first transaction commits?
7. Which compensations are required after partial success?
8. Which tenant isolation guarantees should be enforced below application code?
9. Which patterns solve the actual problem, and which ones are ceremony?

If the answers are clear, DDD gives you a vocabulary and a set of tools. If the answers are not clear, start with more domain discovery, not more abstractions.