Software Architecture
Domain models, aggregates and repositories in NestJS explained
Designing domain models, scoping aggregate boundaries and implementing repository interfaces in NestJS through a product module. Avoid stuffing logic into services.
By Nguyễn Sinh Nhật6 min read
In a real project, I built a product module with 500+ products and 200+ transactions per day. Applying DDD separated business logic from technical concerns and cut bugs from requirement changes by 40%.
Understanding DDD architecture in NestJS
Domain Model: representing the core entities
A domain model is the abstraction representing business concepts. In the product module, each product can have many variants, but only one main entity represents the domain concept. Value-object logic lives in its own class.
@Entity()
export class Product {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column({ type: 'decimal', precision: 10, scale: 2 })
price: number;
@OneToMany(() => ProductVariant, variant => variant.product)
variants: ProductVariant[];
}Value Object: attributes without identity
This value needs no identity, only computation and display. When updating a price, just replace the object instead of mutating entity fields.
export class Price {
constructor(
public amount: number,
public currency: string = 'VND'
) {}
get formatted(): string {
return `${this.amount.toLocaleString()} ${this.currency}`;
}
}Aggregate Boundary: scoping change
An aggregate boundary defines which entities may change together: Product is the aggregate root, with ProductVariant and Stock depending on it. Updating a price only touches Product and its variants, never other aggregates.
- Product is the primary aggregate root.
- ProductVariant depends on Product.
- Stock depends on ProductVariant.
Aggregate relationship diagram
Product
├── ProductVariant
│ └── Stock
└── CategoryProductVariant may never change directly; everything goes through Product. This keeps data consistent.
Repository Interface: separating data access
A repository is the interface between domain and persistence. Every CRUD operation goes through it, making database engine swaps painless.
export interface ProductRepository {
findById(id: number): Promise<Product | null>;
save(product: Product): Promise<Product>;
delete(id: number): Promise<void>;
}Real implementation with TypeORM
@Injectable()
export class ProductTypeORMRepository implements ProductRepository {
constructor(
@InjectRepository(Product)
private readonly repo: Repository<Product>
) {}
async findById(id: number): Promise<Product | null> {
return this.repo.findOne({ where: { id }, relations: ['variants', 'category'] });
}
async save(product: Product): Promise<Product> {
return this.repo.save(product);
}
}Common mistakes when stuffing logic into services
1. Business logic inside services
// Wrong: pricing logic lives in the service
@Injectable()
export class ProductService {
async updatePrice(id: number, newPrice: number) {
const product = await this.repo.findById(id);
if (!product) throw new Error('Product not found');
product.price = newPrice;
await this.repo.save(product);
}
}Fix: extract the calculation into its own class; the service only orchestrates flow.
export class PriceCalculator {
static applyDiscount(price: number, discount: number): number {
return price * (1 - discount);
}
}
// Service only handles flow
async updatePrice(id: number, newPrice: number) {
const product = await this.repo.findById(id);
if (!product) throw new Error('Product not found');
product.price = PriceCalculator.applyDiscount(newPrice, 0.1);
await this.repo.save(product);
}2. Raw queries inside services
// Wrong
async findAvailableProducts() {
return this.repo.query(`SELECT * FROM products WHERE stock > 0`);
}Fix: push conditions down into the repository.
async findAvailableProducts(): Promise<Product[]> {
return this.repo.find({ where: { stock: MoreThan(0) } });
}3. Skipping the repository pattern
// Wrong
async updateStock(id: number, quantity: number) {
const product = await Product.findOne(id);
product.stock += quantity;
await product.save();
}Fix: always go through the injected repository.
async updateStock(id: number, quantity: number) {
const product = await this.repo.findById(id);
if (!product) throw new Error('Product not found');
product.stock += quantity;
await this.repo.save(product);
}A real product-module design
Folder structure
src/
products/
dto/
create-product.dto.ts
update-product.dto.ts
entities/
product.entity.ts
product-variant.entity.ts
interfaces/
product.repository.ts
services/
product.service.ts
controllers/
product.controller.ts
modules/
product.module.tsOrder flow
- Client sends an order-creation request.
- OrderService calls ProductRepository for product info.
- ProductRepository reads from the database.
- OrderService applies business logic (stock check, pricing).
- OrderService calls OrderRepository to persist.
Conclusion
Applying DDD in NestJS separates business logic from technical concerns: easier maintenance, easier extension, fewer requirement-change bugs. Keep domain logic in entities and value objects, access data through repositories, keep business rules out of services, and define aggregate boundaries clearly.
Reference resources
Frequently asked questions
Related posts
Keep exploring articles in this category.
Software Architecture5 min read
How to Choose Server vs Client Components in Next.js: Practical Examples
A practical guide to choosing Server vs Client Components in Next.js, common hydration mismatch mistakes, and how to measure bundle size before and after.
Read article
Software Architecture7 min read
One misplaced use client can make Next.js heavier
Understand Server and Client Component boundaries in Next.js to reduce browser JavaScript without losing interactivity.
Read article