Business Modules Architecture & Extension Guide
When building enterprise business applications (such as law practice management, litigation collaboration, financial risk control, or commerce backends) on top of BitzOrcas.Modern, Business Modules (Modules) represent the sole legitimate location for proprietary business logic, custom aggregate roots, and industry use cases.
Under ADR 0203 (Physical Directory Structure) and ADR 0205 (Commercial Package Distribution & Extension Model), consumer solutions are strictly prohibited from modifying framework internals (src/Framework) or built-in platform capabilities (src/Platform). All custom business features reside strictly within the src/Modules/** physical directory.
1. Physical Directory Structure & Anti-Corruption Isolation (ADR 0203)
1.1 Module Directory Naming Conventions
- Business Category Path:
src/Modules/<DomainCategory>/<ModuleName>/ - Recommended Four-Layer Physical Project Structure:
BitzOrcas.Modules.<ModuleName>.Contracts: Publicly exposed DTOs, interfaces, and integration events;BitzOrcas.Modules.<ModuleName>.Domain: Aggregate roots, entities, value objects, and domain events;BitzOrcas.Modules.<ModuleName>.Application: CQRS Command/Query, Mediator Handlers,IRequestRule<T>validation;BitzOrcas.Modules.<ModuleName>.Infrastructure: SqlSugar / EF Core dual ORM repository adapters, persistence models, and Outbox event dispatchers.
2. Platform Capability Consumption & Extension Patterns (ADR 0205)
Business modules and platform capabilities follow a strict Deep Module unidirectional dependency rule:
| Extension Pattern | Use Case | Architectural Guardrail |
|---|---|---|
| Contracts Reference | Business module needs identity, file, or notification capabilities | Only ProjectReference or PackageReference to *.Contracts is allowed; Architecture tests statically guard against referencing .Application or .Infrastructure |
| Event-Driven Integration (CAP Outbox) | Cross-module state synchronization and workflow triggers | Follows ADR 0304, leveraging RabbitMQ + CAP Outbox to deliver versioned integration events for eventual consistency |
| Dynamic Validation Strategies | Tenant-specific business validation and admission rules | Register ITenantValidationStrategy<TRequest> to enforce tenant-scoped rules in the Mediator pipeline (ADR 0403) |
| Store Port Overriding | Custom data persistence and specialized read models | Implement module-specific Store ports and bind them in the Host composition root |
3. Business Modules Deep-Dive Navigation
To guide engineering teams building production-grade domain modules, this section includes dedicated in-depth chapters:
- Sandbox Golden Sample Architecture: Three-tier physical boundaries, CQRS vertical slices, aggregate roots, and immutable error catalogs;
- Module Lifecycle & Modularity Engine: Dependency graph topological sorting, automatic DI wiring, and middleware registration;
- Profiles & Metapackage Tailoring Architecture: Metapackage orchestration for tenant-specific editions, deployment footprints, and commercial delivery.
4. Built-in Platform Capabilities
When developing business modules, prioritize reusing the 36 mature infrastructure and domain capabilities provided by the platform:
Explore 36 Platform Capabilities in the Platform Center
Including: