ADR 0203: Physical Directory Structure Framework + Modules

Status

Accepted

Date

2026-06-30

Context

BitzOrcasVNext historically used a flat BuildingBlocks/ + Platform/ layout under src/. As the modular monolith matured and business modules grew, this layout introduced two major issues:

Semantic Ambiguity: BuildingBlocks did not clearly communicate “framework foundation”, while Platform blurred the boundary between system-level platform capabilities and business modules.
Insufficient Anti-Corruption Isolation: Framework cores (Domain, Application, Infrastructure, Source Generators) resided alongside default Platform capabilities in the same tier, risking tight coupling during feature evolution.

Proven architectures like ABP demonstrate that technical foundations and business modules should be physically separated to eliminate accidental coupling.

Decision

Reorganize the top-level src/ directory into Framework/ + Platform/ + Modules/:

1. BuildingBlocks → Framework

src/Framework/ contains pure technical framework building blocks with zero business dependencies:

Sub-Group	Projects	Responsibility
Core	Domain / Application / Modularity	Domain primitives, application pipelines, module governance
SourceGenerators	DI.Attributes / DI.SourceGenerator / Endpoint.SourceGenerator	Reflection-free compile-time DI and endpoint discovery (ADR 0103)
CodeGeneration	CodeGeneration.Abstractions / CodeGeneration.Scriban	Template code generation and input audit
Persistence.Metadata	Persistence.Metadata / Persistence.Metadata.Generator	Provider-neutral metadata and ORM Fluent configuration generators
Infrastructure	Infrastructure / Infrastructure.SqlSugar / EfCore / Dapper / Storage.S3Compatible	Database adapters and storage drivers
Workflow	Workflow.Abstractions / Engine / Persistence / SqlSugar / EfCore / Dapper	Self-built lightweight high-performance workflow engine

2. Platform → src/Platform

src/Platform/ is the canonical home for default template platform capabilities. It sits alongside src/Modules/**, physically demarcating template assets from customer business code.

Location	Role	Status
`src/Platform/**`	Target structure for default Platform assets; houses 36 built-in platform capabilities	Canonical
`src/Modules/<Category>/<Module>/**`	Business domain modules created by adopters	Business
`src/Modules/Sandbox/**`	Reference implementation and architectural test sandbox	Sample

Adopters building business applications must create their business modules under /src/Modules/{BusinessModule}/ rather than modifying default Platform source trees.

3. Invariants

Assembly Names Unchanged: All .csproj <AssemblyName> tags remain unchanged (e.g., BitzOrcas.Platform.Application).
Namespaces Unchanged: All C# namespace declarations remain intact.
Hosts and Tooling Unchanged: src/Hosts/ and src/Tooling/ remain in place.

Constraints

Project file names (.csproj) are not renamed; only physical directory paths are restructured.
New built-in platform capabilities must be placed under src/Platform/<Capability>/.
New business modules must be placed under src/Modules/.