Design & Architecture

Domain Modelling & Boundaries

Intermediate

Software is easiest to understand when its structure matches the real business. Domain modelling means using the language and concepts the business actually uses, and drawing clear boundaries between distinct areas (onboarding, screening, payments) so each can evolve on its own. Good boundaries keep a growing system from turning into one tangled mess.

Ideas from Domain-Driven Design help here, without the extra process. Use a shared, precise vocabulary (the same words in code, conversation, and the UI), and identify bounded contexts: areas of the system with their own model and clear edges. Inside a context the model is consistent. Between contexts, you translate at the boundary instead of sharing one giant model that everyone fights over.

This is the higher-level companion to Separation of Concerns (within code) and Data Modelling (the data). For us, the natural boundaries match the business: KYC and onboarding, screening and AML, payments, customers. Each has its own rules and changes at its own pace.

Model the business honestly

DoUse the business's own language consistently in code, APIs, and docs (a "customer", "case", or "screening hit" means the same thing everywhere). A shared vocabulary prevents many misunderstandings.
DoIdentify distinct areas (bounded contexts) and give each clear responsibilities and edges, so a change in one rarely spreads into others (see Separation of Concerns).
DoKeep each context's model focused on its own needs. Do not force one universal model to serve every area.
ConsiderTranslating explicitly at boundaries (mapping between contexts) instead of sharing internal models across them.
AvoidA single large "shared" model that every part depends on. It couples everything together and becomes impossible to change safely.

One model for everything

// a single giant Customer object used by onboarding, screening,
// payments and support — every team edits it, nobody owns it

Every area is coupled to one bloated model. A change for payments breaks screening, and the shared object gathers fields nobody fully understands. The boundaries have collapsed.

Bounded contexts with contracts

// Onboarding has its CustomerProfile; Screening has its ScreeningSubject;
// Payments has its Payer — each focused, owned, and connected via
// explicit APIs/events, mapping at the boundary

Each area models what it needs, owns its own changes, and integrates through clear contracts. So teams can move independently without breaking each other.

Keep boundaries clean

DoLet contexts talk through clear contracts (APIs, events), not by reaching into each other's internals or database tables (see API & Contract Design, Asynchronous Messaging).
DoLet boundaries reflect ownership and rate of change. Areas that change together and are owned together belong together.
ConsiderHow tenancy, consistency, and transactions fit each boundary. Some need strong consistency within a context; across contexts, eventual consistency is often fine (see Distributed Systems & Consistency).
AvoidSplitting too early into many tiny services or contexts before you understand the domain. Wrong boundaries are costly to move, so it is often better to start modular and split later.

Self-review checklist

AskDoes the code use the business's real language, consistently?
AskIs this in the right area, with clear responsibility and edges?
AskAm I coupling areas by sharing a model or reaching into another's data, instead of using a contract?
AskAre these boundaries based on real ownership and change, or split arbitrarily?

Why it matters: Clear domain boundaries let a system, and the teams building it, grow without grinding to a halt. When the model matches the business and contexts have clean edges, changes stay local and the code is understandable. When everything shares one tangled model, every change is risky and slow. Getting boundaries roughly right is one of the most valuable design decisions you can make.