Table of Contents

JD.Domain Suite v1 — Complete Roadmap

This document outlines the complete implementation plan for JD.Domain Suite v1, based on the original issue specification.

Overview

The goal is to ship a production-ready, opt-in domain modeling + rules + configuration suite that can be adopted in any codebase (database-first or code-first), interoperates seamlessly with EF Core reverse-engineered models, and supports two-way generation.

Implementation Milestones

✅ Milestone 1 — Abstractions + Manifest (COMPLETED)

Status: Complete (commit 3cd0f59)

Deliverables:

  • ✅ JD.Domain.Abstractions package with core contracts
  • ✅ DomainManifest model with all manifest types (21 types)
  • ✅ Result monad for functional error handling
  • ✅ DomainError model with severity and metadata
  • ✅ Core interfaces (IDomainEngine, IDomainFactory)
  • ✅ RuleEvaluationResult and RuleEvaluationOptions
  • ✅ Comprehensive unit tests (13 passing tests)

✅ Milestone 2 — DSLs (COMPLETED)

Status: Complete (commits ceeaa4b, 81bc0c1, b8d4fd2)

Deliverables:

  • ✅ JD.Domain.Modeling package
    • Fluent DSL entry point: Domain.Create(name)
    • DomainBuilder with Entity, ValueObject, Enum
    • Reflection-based model discovery
    • Type metadata extraction
  • ✅ JD.Domain.Configuration package
    • Configuration DSL mirroring EF Core
    • Keys (primary, alternate)
    • Properties (required, length, precision)
    • Indexes (unique, filtered, included properties)
    • Table mapping (name, schema)
    • Relationship/inheritance infrastructure (hooks prepared)
  • ✅ JD.Domain.Rules package
    • Invariants, Validators, Policies, Derivations
    • State transitions infrastructure
    • RuleContext support
    • Rule composition (Include, When)
    • Severity levels and custom messages
  • ✅ Merge and precedence system (prepared)
  • ✅ Unit tests for all DSL packages

✅ Milestone 3 — Runtime (COMPLETED)

Status: Complete (commits c674558, b8d4fd2)

Deliverables:

  • ✅ JD.Domain.Runtime package
    • DomainRuntime.Create() implementation
    • Synchronous rule evaluation engine
    • Asynchronous rule evaluation engine
    • IDomainEngine implementation
    • Rule set filtering by name
    • Error/warning/info collection
    • Evaluation metrics
  • ✅ Telemetry hooks prepared (OpenTelemetry-ready)
  • ✅ Standalone entry points (non-DI usage)
  • ✅ Unit tests for runtime

✅ Milestone 4 — EF Core Adapter (COMPLETED)

Status: Complete (commit 6c15f0d)

Deliverables:

  • ✅ JD.Domain.EFCore package (net10.0, EF Core 10.0.1)
    • ModelBuilder.ApplyDomainManifest() extension
    • Apply entity configurations from manifests
    • Property configuration (required, max length)
    • Index configuration (unique, filtered)
    • Key configuration
    • Table mapping (name, schema)
  • ⏳ SaveChanges interceptors (infrastructure prepared, not implemented)
  • ⏳ Domain event emission (infrastructure prepared)
  • ⏳ Mapper utilities (infrastructure prepared)

✅ Milestone 5 — Generators (Core) (COMPLETED)

Status: Complete (commit 1b5eda2)

Deliverables:

  • ✅ JD.Domain.Generators.Core package
    • BaseCodeGenerator abstract class
    • ICodeGenerator interface
    • GeneratorContext for manifest and options
    • GeneratorPipeline for chaining generators
    • GeneratedFile representation
    • CodeBuilder fluent API with:
      • Auto-generated headers with version info
      • Using statements, namespaces
      • Class/interface/method generation
      • Indentation tracking
    • GeneratorUtilities for common operations
  • ✅ Deterministic generation infrastructure
    • Stable file naming and ordering
    • Version hash headers
    • Auto-generated markers
  • ✅ Generator tests

✅ Milestone 6 — FluentValidation Generator (COMPLETED)

Status: Complete (commits c29b47a, 72c4ad3)

Deliverables:

  • ✅ JD.Domain.FluentValidation.Generator package
    • Generator: JD rules → FluentValidation
    • Map Invariant rules to validator rules
    • Map Validator rules with proper selectors
    • Generate AbstractValidator classes
    • Property path resolution from expressions
    • Custom error messages with escaping
    • Severity mapping
  • ✅ Integration with FluentValidation 11.x
  • ✅ Generator tests

✅ Milestone 7 — Domain Model Generator (COMPLETED)

Status: Complete (implemented proxy-wrapper approach)

Deliverables:

  • ✅ JD.Domain.DomainModel.Generator package
    • Generates domain proxy types (e.g., DomainBlog) that wrap EF entities
    • Construction-safe API with static Create methods returning Result
    • FromEntity() for wrapping existing tracked entities
    • Implicit conversion to EF entity for EF interop
    • Property-level rule enforcement in setters
    • With*() mutation methods returning Result
    • Partial class support for semantic method extensions
    • DomainContext parameter support for policies/auditing
    • Configurable options (namespace, prefix, validation mode)
  • ✅ DomainValidationException for property setter failures
  • ✅ RuleEvaluationOptions extended with PropertyName support
  • ✅ 25 unit tests for generator behavior

✅ Milestone 8 — ASP.NET Core Integration (COMPLETED)

Status: Complete

Deliverables:

  • ✅ JD.Domain.Validation package
    • DomainValidationError record for API-friendly errors
    • ValidationProblemDetails extending ProblemDetails
    • ProblemDetailsBuilder fluent builder
    • ValidationProblemDetailsFactory for creating from results/exceptions
  • ✅ JD.Domain.AspNetCore package
    • UseDomainValidation() middleware for exception handling
    • DomainExceptionHandler (IExceptionHandler) integration
    • DomainValidationOptions for configuration
    • Minimal API extensions (.WithDomainValidation())
    • DomainValidationEndpointFilter for endpoint validation
    • MVC action filter ([DomainValidation] attribute)
    • IDomainContextFactory + HttpDomainContextFactory
    • AddDomainValidation() service registration
  • ✅ Unit tests for Validation and AspNetCore packages

✅ Milestone 9 — Snapshot/Diff/Migration + CLI (COMPLETED)

Status: Complete

Deliverables:

  • ✅ JD.Domain.Snapshot package
    • DomainSnapshot model with metadata and hash
    • SnapshotWriter with canonical JSON serialization
    • SnapshotReader for deserialization
    • SnapshotStorage for file operations
    • SnapshotOptions for configuration
    • SHA-256 hash generation for change detection
    • Alphabetically sorted arrays for deterministic output
    • Version metadata and schema reference
  • ✅ JD.Domain.Diff package
    • DiffEngine for snapshot comparison
    • Change detection for entities, properties, value objects, enums, rule sets, configurations
    • BreakingChangeClassifier for breaking vs non-breaking classification
    • DiffFormatter with Markdown and JSON output
    • MigrationPlanGenerator for recommended migration steps
    • Change records (EntityChange, PropertyChange, ValueObjectChange, etc.)
  • ✅ JD.Domain.Cli package (tool command: jd-domain)
    • Command: jd-domain snapshot --manifest --output
    • Command: jd-domain diff [--format md|json]
    • Command: jd-domain migrate-plan [--output ]
    • System.CommandLine for parsing
    • PackAsTool support for global tool installation
  • ✅ Unit tests for Snapshot and Diff packages (22 new tests)
  • ⏳ MSBuild integration targets (deferred to future milestone)

✅ Milestone 10 — T4 Shims (COMPLETED)

Status: Complete

Deliverables:

  • ✅ JD.Domain.T4.Shims package
    • T4ManifestLoader for loading manifests in T4 templates
    • T4TypeMapper for CLR to C#/SQL type mapping
    • T4CodeBuilder for T4-friendly code generation
    • T4EntityGenerator for entity code generation
    • T4OutputManager for deterministic multi-file output
  • ✅ Unit tests (31 tests)

✅ Milestone 11 — Tests + Samples + Docs (COMPLETED)

Status: Complete

Deliverables:

  • ✅ Complete test suite (187 tests passing)
    • Unit tests for all packages
    • Generator tests
    • Snapshot/Diff tests
    • T4 Shim tests
  • ✅ Sample applications
    • JD.Domain.Samples.CodeFirst (code-first workflow)
    • JD.Domain.Samples.DbFirst (database-first workflow)
    • JD.Domain.Samples.Hybrid (mixed sources with snapshot/diff)
  • ✅ Documentation
    • Updated ROADMAP with complete milestone status
    • Updated README with current status and examples
    • Essential getting started content

✅ Milestone 12 — Final Release Preparation (COMPLETED)

Status: Complete

Deliverables:

  • ✅ Verify all v1 acceptance criteria
  • ✅ Run full test suite across all packages (187 tests passing)
  • ✅ Update README with complete examples
  • ✅ Add NuGet package metadata (Directory.Build.props)
    • Authors, Copyright, License
    • Package tags for discoverability
    • Source Link for debugging
    • Deterministic builds enabled
    • Symbol packages (snupkg)
  • ✅ Verify deterministic builds
  • ⏳ Security review with CodeQL (optional for v1)
  • ⏳ Performance benchmarks (optional for v1)
  • ✅ Release notes (see CHANGELOG.md)
  • 📋 Tag v1.0.0 (pending final approval)

Total Estimated Effort

20-28 weeks (approximately 5-7 months) for a complete v1 implementation.

This assumes:

  • Focused development time
  • Iterative feedback and refinement
  • Community contributions for samples and documentation

v1 Acceptance Criteria

  1. ✅ Database-first workflow: Generate JD partials from existing EF models/configs
  2. ✅ Code-first workflow: Author JD DSL and generate EF configs
  3. ✅ Round-trip equivalence: EF → JD → EF produces equivalent model
  4. ✅ Domain types enforce invariants without external validation calls
  5. ✅ Snapshot/diff/migration is deterministic and CI-friendly
  6. ✅ Everything is opt-in; no forced dependencies

Current Progress

Milestone 1: ✅ Complete Milestone 2: ✅ Complete Milestone 3: ✅ Complete Milestone 4: ✅ Complete Milestone 5: ✅ Complete Milestone 6: ✅ Complete Milestone 7: ✅ Complete Milestone 8: ✅ Complete Milestone 9: ✅ Complete Milestone 10: ✅ Complete Milestone 11: ✅ Complete Milestone 12: ✅ Complete

Overall Progress: 100% of v1 scope complete (12/12 milestones)

Test Status: 187 tests passing, 0 failures

Release Status

v1.0.0 is ready for release pending final approval and tagging.

Contributing

Given the scope, contributions are highly welcome! Areas where help is needed:

  • DSL design and implementation
  • Source generator expertise
  • EF Core integration patterns
  • Documentation and samples
  • Testing and feedback

Notes

This is an ambitious project with a clear vision. The modular architecture allows for incremental delivery and adoption. Each milestone can be released independently as preview packages.

Edit this page