.NET Architecture Best Practices

Apply these practices when designing, building, reviewing, or refactoring .NET applications that benefit from structured domain modeling and layered architecture.

Core Principles

Domain-Driven Design (DDD)

DDD aligns software design with business reality. The goal is to make the codebase a direct expression of business concepts, so domain experts and developers share a common vocabulary and the system remains adaptable as the business evolves.

• Ubiquitous Language: Use consistent business terminology throughout code, documentation, and conversation. When the business calls something an "Order," the code should use Order -- not PurchaseRecord or TransactionItem. This reduces translation errors and keeps the model honest.
• Bounded Contexts: Define clear service boundaries where a particular domain model applies. Each bounded context has its own ubiquitous language and data ownership. Communicate across boundaries through well-defined contracts (domain events, APIs), not shared databases.
• Aggregates: Design consistency boundaries that protect business invariants. Each aggregate has a root entity that controls access to its children and enforces rules within a single transaction. Keep aggregates small -- large aggregates cause contention and performance issues.
• Domain Events: Capture business-significant occurrences as first-class objects (e.g., OrderPlaced, PaymentReceived). Domain events decouple bounded contexts, enable audit trails, and support eventual consistency across service boundaries.
• Rich Domain Models: Place business logic in the domain layer, not in application services or controllers. Entities and value objects should enforce their own invariants, making invalid states unrepresentable.

For detailed patterns including aggregate design rules, value object implementation, and domain event handling, see references/domain-layer.md.

SOLID Principles