Carrot

Appearance

Carrot.Data.Scaffold.Compilers.Modules.Domain ​

net

Scaffold compiler module that generates domain layer documentation from the combined API and database scaffold graphs.

Installation ​

xml
<ProjectReference Include="..\Carrot.Data.Scaffold.Compilers.Modules.Domain\Carrot.Data.Scaffold.Compilers.Modules.Domain.csproj" />

Architecture ​

Composite Graph Root ​

Unlike other scaffold modules that operate on a single graph root (ScaffoldApi or ScaffoldDatabase), the Domain module uses ScaffoldDomain - a composite that holds references to both:

csharp
public class ScaffoldDomain
{
    public ScaffoldApi Api { get; init; }
    public ScaffoldDatabase Database { get; init; }
}

The ScaffoldCompilerDomain.GraphRoot property lazily constructs this from this.Scaffold.ScaffoldApi and this.Scaffold.ScaffoldDatabase.

Compiler Module ​

ScaffoldCompilerDomain extends ScaffoldCompilerModule<ScaffoldDomain, ScaffoldCompilerDomainOptions>. It configures:

  1. A single ScaffoldCompilerDomainRendererReadme for the collection root
  2. One ScaffoldCompilerDomainRendererApiReadme per API in the scaffold graph

Renderers ​

Both renderers produce ScaffoldCompilerRendererOutputDisclose (markdown/disclose format) documentation files:

  • Root readme - collection-level domain documentation with the collection name
  • Per-API readme - API-level domain documentation with the API name

Output Structure ​

Platform/Domain/{Collection}/
  Carrot.Platform.Domain.{Collection}/
    readme.md              # Collection root domain readme
  Carrot.Platform.Domain.{Collection}.{Api}/
    readme.md              # Per-API domain readme

Dependencies ​

DependencyKind
Carrot.Data.Scaffold.Compilersproject (scaffold compiler framework)

Build ​

bash
dotnet build

Targets net10.0.

Usage Guide ​

Generate domain layer documentation from the combined API and database scaffold graphs.

Getting Started ​

Register the Domain module on a scaffold compiler:

csharp
IScaffoldCompiler compiler = scaffold.CreateCompiler()
    .AddModuleDomain();

Typically used alongside the Api and EntityFramework modules:

csharp
IScaffoldCompiler compiler = scaffold.CreateCompiler()
    .AddModuleApi()
    .AddModuleEntityFramework()
    .AddModuleDomain();

Then compile:

csharp
IScaffoldCompilerResult result = compiler.Compile();

Common Patterns ​

Composite Graph ​

The Domain module is unique in that it combines both the API and database graphs into a single ScaffoldDomain root. This allows domain documentation to reference both API contracts and database entities.

csharp
// The ScaffoldDomain is constructed internally:
// ScaffoldDomain { Api = scaffold.ScaffoldApi, Database = scaffold.ScaffoldDatabase }

Generated Output ​

The module generates markdown readme files at two levels:

  1. Collection root - Platform/Domain/{Collection}/Carrot.Platform.Domain.{Collection}/readme.md
  2. Per API - Platform/Domain/{Collection}/Carrot.Platform.Domain.{Collection}.{Api}/readme.md

These provide documentation scaffolding for the domain project structure.

Tips ​

  • Requires both graphs - the scaffold must have both ScaffoldApi and ScaffoldDatabase populated for the Domain module to function correctly.
  • Documentation only - this module currently generates documentation/readme files, not executable C# code. The domain interfaces for controllers are generated by the Api module's controller renderer.

Carrot