I needed my CRM to scale properly, so I decided to use Microsoft Orleans in the infrastructure layer. With Aspire, you can scale each silo automatically.

Sounds great, right? But there's a catch.

Why Aspire is Worth It

Aspire was built to simplify deployment and deliver one of the best developer experiences Microsoft has created. In my opinion, it sits alongside ASP.NET Core and Microsoft Orleans as the best things Microsoft has shipped in years.

When you deploy with Aspire, the Azure Developer CLI (azd) generates a manifest file, creates Bicep infrastructure files, pushes container images to Azure Container Registry (ACR), and updates your Azure Container Apps with the new versions. All with a single command.

But if you deploy with default settings, several things will hit you hard in production.

The Difference Between Provisioning and Deploying

This is the first trap.

azd up does both provisioning AND deployment. If you run it again, it will replace your entire infrastructure and eliminate all your data. Be extremely careful with this command in production.

azd deploy is what you want for regular deployments. It only deploys your code changes without touching your infrastructure. Use this for your CI/CD pipelines after the initial setup.

The lesson here is simple: provision once, deploy many times.

Secrets Don't Persist by Default

Here's another gotcha that will waste hours of your time.

When you first run azd up, it prompts you for parameters and secrets. Those values get stored locally in ~/.aspire/deployments/{AppHostSha}/{environment}.json. The problem? Every time you deploy, you might need to reconfigure environment variables in the Azure portal.

The solution is using AddParameter with the secret: true flag. This creates proper parameter resources that persist across deployments. When combined with Azure Key Vault integration, your secrets remain stable between deployments instead of being regenerated or lost.

Additionally, using azd provision separately will prompt for secrets and store them in a local vault file, making subsequent azd deploy commands smoother.

The ACR Cost Explosion

Now let's talk about what will really kill your wallet: Azure Container Registry.

ACR has no free tier. Here's the pricing breakdown:

Here's where it gets ugly

Every single deploy creates a new container image. These images are stored for rollback purposes—or as I see it, it's Microsoft's way of making money from accumulated storage.

If you have multiple services in your Aspire solution (and you probably do), each one generates a new image on every deployment. Deploy 3 services twice a day for a month? That's 180 images. At the end of the month, you could easily have 10+ GB of space used in ACR.

And it doesn't stop there. The storage overage charges apply daily. Within 6 months, you could be paying up to 500% more than you expected.

This is a business. Always approach technology pragmatically.

How I Solved It

ACR has a feature called ACR Tasks that can run scheduled commands. You can create a purge task that automatically cleans up old images.

What I did is simple: every 6 hours, a scheduled task searches for all images in the ACR and deletes everything except the 3 most recent images per repository.

The command uses acr purge with these key parameters:

You can run a dry-run first to see what would be deleted without actually removing anything. Once you're confident, schedule the task using a cron expression.

This approach has saved me significant money over time. In the long run, your wallet will thank you.

Final Thoughts

Aspire is an incredible technology for local development and cloud deployment. Azure Container Apps gives you serverless scaling with built-in Kubernetes (KEDA) for autoscaling based on CPU, memory, or custom events.

But remember:

1. Use azd deploy for regular deployments, not azd up

2. Configure your parameters properly with AddParameter to persist secrets

3. Set up ACR purge tasks from day one to control storage costs

4. Monitor your ACR usage regularly in the Azure Portal

The convenience of Aspire is real. The costs of not understanding these details are also very real.

Building a system that talks to multiple platforms? You've probably written code like this:

public class Platform
{
    public string Name { get; set; }

    // Text stuff
    public bool SupportsText { get; set; }
    public int MaxTextLength { get; set; }
    public bool SupportsMarkdown { get; set; }
    public bool SupportsHtml { get; set; }

    // Voice stuff
    public bool SupportsVoice { get; set; }
    public int MaxVoiceDuration { get; set; }
    public string[] SupportedVoiceCodecs { get; set; }

    // Files
    public bool SupportsFiles { get; set; }
    public long MaxFileSize { get; set; }
    public string[] AllowedMimeTypes { get; set; }

    // Reactions
    public bool SupportsReactions { get; set; }
    public string[] AllowedReactions { get; set; }

    // ...and it keeps growing
}

This works at first. Then it becomes a nightmare. You end up with 50+ properties, half of them nullable, and you're never quite sure which combinations are valid. SupportsVoice = true but SupportedVoiceCodecs = null? That's a runtime bug waiting to happen.

The real pain hits when you're trying to figure out what a platform can actually do. You scan through dozens of boolean flags, hoping you didn't miss one. Your validation logic is scattered everywhere. Testing means setting up massive mock objects.

What If We Treated Capabilities as Components?

Here's a different approach. Instead of boolean flags with loosely-related configuration, we make each capability its own thing - a well-defined interface that either exists or doesn't.

The idea is straightforward:

• Each capability is an interface with its own rules

• Platforms compose themselves by adding capabilities they support

• Your code asks "do you have X?" before trying to use it

• Everything is type-safe and the compiler helps you

Let's build it.

Defining Capabilities

Start with interfaces for each capability:

public interface IPlatformCapability 
{
    string CapabilityName { get; }
}

public interface ITextMessageCapability : IPlatformCapability
{
    int MaxLength { get; }
    bool SupportsMarkdown { get; }
    bool SupportsHtml { get; }
}

public interface IVoiceMessageCapability : IPlatformCapability
{
    int MaxDurationSeconds { get; }
    List<string> SupportedCodecs { get; }
}

public interface IFileUploadCapability : IPlatformCapability
{
    long MaxFileSizeBytes { get; }
    List<string> AllowedMimeTypes { get; }
}

public interface IReactionCapability : IPlatformCapability
{
    List<string> AllowedReactions { get; }
    int MaxReactionsPerMessage { get; }
}

Each interface groups related properties together. If you have IVoiceMessageCapability, you know you'll get MaxDurationSeconds and SupportedCodecs - they come as a package.

Platform-Specific Implementations

Now implement these for each platform. Here's where it gets interesting - you can add platform-specific properties that go beyond the interface:

public class WhatsAppTextCapability : ITextMessageCapability
{
    public string CapabilityName => "Text";
    public int MaxLength => 4096;
    public bool SupportsMarkdown => true;
    public bool SupportsHtml => false;

    // WhatsApp-specific stuff
    public List<string> SupportedMentionTypes => new() { "@user", "@all" };
}

public class WhatsAppVoiceCapability : IVoiceMessageCapability
{
    public string CapabilityName => "Voice";
    public int MaxDurationSeconds => 900;
    public List<string> SupportedCodecs => new() { "opus", "aac" };

    // WhatsApp does auto-transcription
    public bool AutoTranscriptionAvailable => true;
}

public class TelegramTextCapability : ITextMessageCapability
{
    public string CapabilityName => "Text";
    public int MaxLength => 4096;
    public bool SupportsMarkdown => true;
    public bool SupportsHtml => true; // Telegram supports HTML!

    // Telegram-specific
    public List<string> SupportedEntityTypes => new() 
    { 
        "mention", "hashtag", "url", "bot_command" 
    };
}

public class TelegramFileCapability : IFileUploadCapability
{
    public string CapabilityName => "FileUpload";
    public long MaxFileSizeBytes => 2L * 1024 * 1024 * 1024; // 2GB
    public List<string> AllowedMimeTypes => new() { "*/*" };

    public bool SupportsFileStreaming => true;
}

public class SmsTextCapability : ITextMessageCapability
{
    public string CapabilityName => "Text";
    public int MaxLength => 160;
    public bool SupportsMarkdown => false;
    public bool SupportsHtml => false;

    public bool AutoSplitLongMessages => true;
    public int MaxConcatenatedSegments => 10;
}

Notice how SMS doesn't have voice or file capabilities - it just doesn't implement those interfaces. That's the point.

The Platform Class

This is where capabilities live:

public class Platform
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Provider { get; set; }

    private readonly Dictionary<Type, IPlatformCapability> _capabilities = new();

    public void AddCapability<T>(T capability) where T : IPlatformCapability
    {
        _capabilities[typeof(T)] = capability;
    }

    public bool HasCapability<T>() where T : IPlatformCapability
    {
        return _capabilities.ContainsKey(typeof(T));
    }

    public T GetCapability<T>() where T : IPlatformCapability
    {
        return _capabilities.TryGetValue(typeof(T), out var capability) 
            ? (T)capability 
            : default;
    }

    public TConcrete GetConcreteCapability<TConcrete>() 
        where TConcrete : class, IPlatformCapability
    {
        return _capabilities.Values.OfType<TConcrete>().FirstOrDefault();
    }
}

Pretty simple. It's just a type-safe registry of capabilities.

Setting Up Platforms

public class PlatformFactory
{
    public Platform CreateWhatsApp()
    {
        var platform = new Platform 
        { 
            Id = Guid.NewGuid(),
            Name = "WhatsApp Business",
            Provider = "whatsapp"
        };

        platform.AddCapability(new WhatsAppTextCapability());
        platform.AddCapability(new WhatsAppVoiceCapability());
        platform.AddCapability(new WhatsAppReactionCapability());
        platform.AddCapability(new WhatsAppFileCapability());

        return platform;
    }

    public Platform CreateTelegram()
    {
        var platform = new Platform 
        { 
            Id = Guid.NewGuid(),
            Name = "Telegram Bot",
            Provider = "telegram"
        };

        platform.AddCapability(new TelegramTextCapability());
        platform.AddCapability(new TelegramFileCapability());
        // No reactions - Telegram doesn't support them

        return platform;
    }

    public Platform CreateSMS()
    {
        var platform = new Platform 
        { 
            Id = Guid.NewGuid(),
            Name = "SMS Gateway",
            Provider = "sms"
        };

        platform.AddCapability(new SmsTextCapability());
        // Just text, nothing else

        return platform;
    }
}

Look how clear this is. You can see exactly what each platform supports.

Using It

Here's where it pays off:

public class MessageService
{
    public async Task<Result> SendTextMessage(Platform platform, string text)
    {
        // Check if the platform can do this
        if (!platform.HasCapability<ITextMessageCapability>())
        {
            return Result.Fail($"{platform.Name} doesn't support text messages");
        }

        // Get the capability - it's never null here
        var textCap = platform.GetCapability<ITextMessageCapability>();

        // Validate
        if (text.Length > textCap.MaxLength)
        {
            return Result.Fail($"Text too long (max {textCap.MaxLength} characters)");
        }

        // Handle markdown
        var processedText = textCap.SupportsMarkdown 
            ? ProcessMarkdown(text) 
            : StripMarkdown(text);

        var handler = GetHandler(platform.Provider);
        return await handler.SendTextAsync(processedText);
    }

    public async Task<Result> SendVoiceMessage(
        Platform platform,
        Stream audioStream,
        string codec)
    {
        if (!platform.HasCapability<IVoiceMessageCapability>())
        {
            return Result.Fail($"{platform.Name} doesn't support voice");
        }

        var voiceCap = platform.GetCapability<IVoiceMessageCapability>();

        if (!voiceCap.SupportedCodecs.Contains(codec))
        {
            return Result.Fail(
                $"Codec '{codec}' not supported. Use: {string.Join(", ", voiceCap.SupportedCodecs)}");
        }

        var handler = GetHandler(platform.Provider);
        return await handler.SendVoiceAsync(audioStream, codec);
    }

    public async Task<Result> AddReaction(
        Platform platform,
        string messageId,
        string emoji)
    {
        if (!platform.HasCapability<IReactionCapability>())
        {
            return Result.Fail($"{platform.Name} doesn't support reactions");
        }

        var reactionCap = platform.GetCapability<IReactionCapability>();

        if (!reactionCap.AllowedReactions.Contains(emoji))
        {
            return Result.Fail(
                $"Emoji '{emoji}' not allowed on {platform.Name}");
        }

        var handler = GetHandler(platform.Provider);
        return await handler.AddReactionAsync(messageId, emoji);
    }
}

The pattern is consistent: check for capability, get it, validate with it, delegate to handler.

When You Need Platform-Specific Stuff

Sometimes you need to access properties that only exist on a specific platform:

public async Task<Result> SendWithAutoTranscription(
    Platform platform,
    Stream voiceStream)
{
    // First check the interface
    if (!platform.HasCapability<IVoiceMessageCapability>())
    {
        return Result.Fail("Voice not supported");
    }

    // Get the concrete WhatsApp implementation
    var whatsappVoice = platform.GetConcreteCapability<WhatsAppVoiceCapability>();

    if (whatsappVoice == null)
    {
        return Result.Fail("Auto-transcription only available on WhatsApp");
    }

    if (!whatsappVoice.AutoTranscriptionAvailable)
    {
        return Result.Fail("Auto-transcription not available");
    }

    // Use WhatsApp-specific feature
    return await SendWithTranscription(voiceStream);
}

Comparing Approaches

Let's see how this stacks up against the traditional ways.

Feature Flags (The Common Way)

public class Platform
{
    public bool SupportsVoice { get; set; }
    public int MaxVoiceDuration { get; set; }
    public string[] SupportedVoiceCodecs { get; set; }
    // ... 50 more properties
}

// Using it
if (!platform.SupportsVoice)
    return Result.Fail("Not supported");

if (platform.MaxVoiceDuration <= 0)
    return Result.Fail("Invalid config");

if (platform.SupportedVoiceCodecs == null || platform.SupportedVoiceCodecs.Length == 0)
    return Result.Fail("No codecs configured");

Problems:

• Properties can be inconsistent (SupportsVoice = true but SupportedVoiceCodecs = null)

• Class gets huge as you add platforms

• No way to know which properties go together

• Easy to forget validation checks

• Testing means mocking tons of properties

Strategy Pattern (The OOP Way)

public interface IMessageSender
{
    Task<Result> SendTextAsync(string text);
    Task<Result> SendVoiceAsync(Stream audio, string codec);
    Task<Result> SendFileAsync(Stream file, string mimeType);
    Task<Result> AddReactionAsync(string messageId, string emoji);
}

public class SmsSender : IMessageSender
{
    public Task<Result> SendTextAsync(string text)
    {
        // Actually implemented
    }

    // SMS doesn't support these, but we're forced to implement them
    public Task<Result> SendVoiceAsync(Stream audio, string codec)
    {
        return Task.FromResult(Result.Fail("Not supported"));
    }

    public Task<Result> AddReactionAsync(string messageId, string emoji)
    {
        return Task.FromResult(Result.Fail("Not supported"));
    }

    public Task<Result> SendFileAsync(Stream file, string mimeType)
    {
        return Task.FromResult(Result.Fail("Not supported"));
    }
}

Problems:

• Interface forces you to implement methods you don't support

• No way to check capabilities before calling

• Validation logic duplicated in every implementation

• Testing requires mocking entire interface

Capability Pattern (Our Way)

// Platform only has capabilities it supports
var sms = new Platform();
sms.AddCapability(new SmsTextCapability());

// Check before using
if (!sms.HasCapability<IVoiceMessageCapability>())
{
    // We know voice isn't supported - don't even try
}

// If it has the capability, we know it's fully configured
var textCap = sms.GetCapability<ITextMessageCapability>();
// textCap is never null here, and all its properties are valid

Benefits:

• Impossible to have inconsistent state

• Clear what each platform supports

• Validation is centralized

• Easy to test (mock just the capability you need)

• New platforms don't change existing code

Real-World Benefits

I've been using this pattern in production for my CRM that integrates with messaging platforms. Here's what I've seen:

Adding a new platform used to take 2-3 days. Now it takes 2-3 hours. I just implement the capabilities it supports and I'm done.

Bug rate dropped significantly. The compiler catches most mistakes. If I try to use a capability that doesn't exist, I get a compilation error, not a runtime crash.

Code is self-documenting. Want to know what WhatsApp supports? Look at which capabilities it has. Want to know the limitations? Look at the capability implementation.

Testing is easier. I mock just the capability I'm testing, not the entire platform.

Onboarding would be faster. When I eventually bring on other developers, they'll understand the system quickly because capabilities are explicit and well-defined.

When To Use This

This pattern makes sense when:

• You integrate with 5+ platforms with different features

• Capabilities change frequently (platforms add features)

• You need type-safe feature detection

• You want to avoid giant classes with dozens of boolean flags

• Testing is important to you

It might be overkill if:

• You only have 2-3 platforms that rarely change

• All platforms support mostly the same things

• You're building an MVP and need to ship fast

Implementation Tips

Start small. Don't try to model every capability upfront. Start with 3-4 core capabilities and expand as needed.

Group related properties. If properties always go together, they belong in the same capability interface.

Make capabilities immutable. Use { get; init; } or readonly properties. Capabilities shouldn't change after creation.

Serialize carefully. If you're using Orleans or need persistence, you'll need a serialization strategy. JSON with type discriminators works well.

Document platform-specific properties. When you add properties beyond the interface, comment why they exist.

Code That Inspired This

This pattern draws from several places:

ASP.NET Core's Feature Collections use a similar approach for HTTP features:

var feature = httpContext.Features.Get<IHttpConnectionFeature>();

ECS (Entity Component System) in game engines uses composable components, though without the systems loop.

Browser feature detection checks for capabilities at runtime:

if ('geolocation' in navigator) {
    // Use geolocation
}

I took these ideas and applied them to platform integration with type-safe interfaces.

Wrapping Up

The Component-Based Capability Pattern isn't revolutionary - it's a synthesis of existing ideas applied to a specific problem. But it works really well for handling platform differences.

Instead of maintaining a growing list of boolean flags, you compose platforms from well-defined capabilities. Your code checks for capabilities before using them. The compiler helps you catch mistakes. Testing is easier. New platforms are straightforward to add.

If you're building something that integrates with multiple platforms, give this pattern a shot. Start with a couple of capabilities and see how it feels. You might find it's exactly what you needed.

I'm using this pattern in production in Kasumi, my CRM built with ASP.NET Core and Microsoft Orleans.

Here's what happened: I was reviewing some Azure Service Bus message processing code that used the standard documented approach with IServiceScopeFactory. When I mentioned that creating scopes for every message could impact performance, especially if message volume grows, I got hit with: "Stop nitpicking. This is the documented best practice, and our volume is low anyway."

This got me thinking about the fine line between nitpicking and legitimate technical concerns. Spoiler alert: they're not the same thing.

So here's what went down

The implementation looked like this:

public class ServiceBusMessageHandler : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var message in messageStream)
        {
            using var scope = _scopeFactory.CreateScope();
            var dbContext = scope.ServiceProvider.GetRequiredService<MyDbContext>();

            await ProcessMessage(message, dbContext);
        }
    }
}

Is this correct? Absolutely. Is it the safest approach? Yes. Could it become a bottleneck? Also yes.

But apparently, pointing this out made me "nitpicky."

Look, there's a difference between being picky and being concerned

Let me clear something up. Real nitpicking in code reviews looks like this:

• "This variable should be called userData instead of data"

• "You're missing a space after the if statement"

• "Use var instead of the explicit type here"

• "This comment has a typo"

Legitimate architectural concerns look like this:

• "This approach might not scale well"

• "This could create memory pressure under load"

• "Have we considered the performance implications?"

• "This pattern has caused issues in similar systems"

See the difference? One is about style preferences. The other is about system design and future-proofing.

But wait, the volume is low so it doesn't matter, right?

Here's where things got really frustrating. The response to my concern was essentially: "Our message volume is low, so it doesn't matter."

This is such a dangerous mindset. Here's why:

Systems Grow

That "low volume" system today could be processing 10x the messages next month. I've seen it happen countless times. You start with 100 messages per day, and suddenly you're dealing with 100,000.

Performance Habits Matter

Building performance awareness into your architecture from day one is way easier than retrofitting it later. It's not about premature optimization—it's about informed design decisions.

The Real Cost of "Later"

Refactoring for performance after the fact typically costs 10x more than considering it upfront. Plus, you're often doing it under pressure when the system is already struggling.

The thing is, most devs today missed the EF Core pain years

Here's something that drives me crazy: many developers today only know EF Core 6+ era, which is genuinely fast and well-optimized. But those of us who lived through EF Core 1.x through 5.x remember the pain:

• Context creation was expensive

• Memory tracking issues were common

• Connection pooling was suboptimal

• Change tracking could kill performance

When I raise concerns about EF Core patterns, I'm not being paranoid—I'm remembering production systems that fell over because we trusted the "best practice" documentation without understanding the trade-offs.

Microsoft docs are great, but they're not optimizing for what you think

Don't get me wrong—Microsoft's documentation is excellent. When they say using IServiceScopeFactory is the best practice for hosted services, they're absolutely right. But "best practice" optimizes for:

• ✅ Safety and correctness

• ✅ Memory leak prevention

• ✅ Proper service lifetimes

• ✅ Threading safety

It doesn't necessarily optimize for:

• ❌ Maximum throughput

• ❌ Minimum resource usage

• ❌ Cost efficiency

• ❌ Performance at scale

Understanding this distinction is crucial.

If you do need to optimize later (and you probably will)

If and when performance becomes important, here are some alternatives:

Batch Processing

// Process messages in batches to amortize scope creation cost
const int batchSize = 50;
using var scope = _scopeFactory.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<MyDbContext>();

foreach (var batch in messages.Chunk(batchSize))
{
    await ProcessBatch(batch, dbContext);
    dbContext.ChangeTracker.Clear(); // Prevent memory buildup
}

IDbContextFactory

// More control over context lifecycle
public class OptimizedMessageHandler
{
    private readonly IDbContextFactory<MyDbContext> _contextFactory;

    public async Task ProcessMessages(IEnumerable<Message> messages)
    {
        using var context = _contextFactory.CreateDbContext();
        // Process multiple messages with same context
    }
}

This isn't really about the code though

The issue isn't the technical implementation—it's the dismissive attitude toward performance considerations. When someone raises a scalability concern, the response should be: "Interesting point. What are you thinking about specifically?" not "Stop nitpicking."

This kind of dismissal shuts down important architectural discussions. It also creates a culture where people stop raising valid concerns because they don't want to be labeled as difficult.

Here's how I see it

Look, I get it. Sometimes we do overthink things. Sometimes a simple, documented approach is exactly what you need. But there's a huge difference between:

• Premature optimization: "Let me write custom assembly code for this string concatenation"

• Architectural awareness: "This pattern might not scale well if our assumptions change"

Raising questions about scalability, especially with historical context, isn't nitpicking—it's good engineering.

So what's the point of all this?

Next time someone dismisses your performance concerns as "nitpicking," ask yourself:

1. Am I worried about style, or system behavior?

2. Could this decision impact future scalability?

3. Am I drawing from real experience with similar patterns?

If you're thinking about system behavior, scalability, and drawing from experience, you're not nitpicking. You're doing your job as a senior developer.

Have you been in similar situations? How do you handle it when architectural concerns get dismissed as nitpicking? I'd love to hear your stories in the comments.

The Challenge with API Endpoints

Traditional API controllers often become bloated with numerous actions, making them difficult to test and maintain. As applications grow, these controllers can accumulate thousands of lines of code, mixing concerns and creating a maintenance nightmare.

Many developers organize APIs by controller, resulting in classes with multiple endpoints that handle different operations on the same resource. While this seems logical at first, it quickly becomes unwieldy as the application grows.

Enter the REPR Pattern

REPR stands for Request-Endpoint-Response, a pattern that focuses on creating dedicated classes for each API endpoint. Instead of controllers with multiple actions, each endpoint is its own class with a single responsibility.

This approach aligns perfectly with SOLID principles, particularly the Single Responsibility Principle. Let's see how I've implemented this using FastEndpoints, a lightweight library that facilitates the REPR pattern in .NET.

Implementation in My Loan Management System

Looking at my loan submission endpoint, you can see how clean and focused the implementation is:

internal class SubmitLoanEndPoint(IStorageProvider storageProvider, ILoanPublisher loanPublisher)
    :Endpoint<SubmitLoanRequest, SubmitLoanResponse>
{
    public override void Configure()
    {
        Post("/");
        Group<LoanGroup>(); 
        AllowAnonymous();
        Summary(s =>
        {
            s.Summary = "Submit a loan application";
            s.Description = "Submit a loan application to the system";
            s.Response<SubmitLoanResponse>();
            s.Response(400, "Invalid request");
            s.Response(500, "Internal server error");
        });
    }

    public override async Task HandleAsync(SubmitLoanRequest req, CancellationToken ct)
    {
        //1.- Create the loan entity
        var loanEntity = new LoanEntity
        {
            LoanId = Guid.NewGuid().ToString(),
            LoanAmount = req.LoanAmount,
            LoanTerm = req.LoanTerm,
            LoanPurpose = req.LoanPurpose,
            BankInformation= new BankInformationEntity(req.BankInformation.BankName, 
                req.BankInformation.AccountType, req.BankInformation.AccountNumber),
            PersonalInformation = new PersonalInformationEntity(req.PersonalInformation.FullName, 
                req.PersonalInformation.Email, 
                DateOnly.FromDateTime(req.PersonalInformation.DateOfBirth)),
        };

        //2.- Save the loan entity to the storage provider
        var loanCreationResult = await storageProvider.CreateLoanAsync(loanEntity);

        //3.- Publish the loan creation event to the message broker
        var loanCreationRequest = new global::Loan.Shared.Contracts.Commands.SubmitLoanRequest(
            loanCreationResult.LoanId,// we pass the loan ID from the storage provider
            req.LoanAmount,
            req.LoanTerm,
            req.LoanPurpose,
            new(req.BankInformation.BankName, req.BankInformation.AccountType, 
                req.BankInformation.BankName),
            new(req.PersonalInformation.FullName, req.PersonalInformation.Email, 
                req.PersonalInformation.DateOfBirth)
        );

        await loanPublisher.PublishLoanSubmittedAsync(loanCreationRequest, ct);

        //4.- Return the loan ID to the client
        await SendOkAsync(new SubmitLoanResponse(loanCreationResult.LoanId), cancellation: ct);
    }
}

Key Components of the REPR Pattern

1. Request Objects

Request objects define the incoming data structure. They're immutable records that clearly communicate what data is needed for this specific endpoint:

internal record SubmitLoanRequest(int LoanAmount,
                                 int LoanTerm,
                                 int LoanPurpose,
                                 BankInfo BankInformation,
                                 PersonalInfo PersonalInformation);

The supporting data types are also simple and immutable:

internal record BankInfo(string BankName, string AccountType, string AccountNumber);

public record PersonalInfo(string FullName, string Email, DateTime DateOfBirth);

2. Endpoint Classes

Each endpoint is a dedicated class that inherits from Endpoint<TRequest, TResponse>. This class has one job: handle a specific API request. The configuration is declarative and self-documented:

public override void Configure()
{
    Post("/");
    Group<LoanGroup>(); 
    AllowAnonymous();
    Summary(s =>
    {
        s.Summary = "Submit a loan application";
        s.Description = "Submit a loan application to the system";
        s.Response<SubmitLoanResponse>();
        s.Response(400, "Invalid request");
        s.Response(500, "Internal server error");
    });
}

Notice how we're using a LoanGroup to organize our endpoints logically:

internal class LoanGroup : Group
{
    public LoanGroup()
    {
        Configure(nameof(Loan).ToLower(), _ =>
        {
            // Group configuration
        });
    }
}

3. Validation

Validation is separated into its own class, keeping the endpoint class clean:

internal class SubmitLoanRequestValidator : AbstractValidator<SubmitLoanRequest>
{
    public SubmitLoanRequestValidator()
    {
        RuleFor(x => x.LoanAmount)
            .NotEmpty()
            .WithMessage("Loan amount is required")
            .GreaterThan(0)
            .WithMessage("Loan amount must be greater than 0");
        RuleFor(x => x.LoanTerm)
            .NotEmpty()
            .WithMessage("Loan term is required")
            .GreaterThan(0)
            .WithMessage("Loan term must be greater than 0");
        RuleFor(x => x.LoanPurpose)
            .NotEmpty()
            .WithMessage("Loan purpose is required");
        RuleFor(x => x.BankInformation)
            .NotNull()
            .WithMessage("Bank information is required");
        RuleFor(x => x.PersonalInformation)
            .NotNull()
            .WithMessage("Personal information is required");
    }
}

4. Response Objects

Response objects are also simple records that define the expected output:

internal record SubmitLoanResponse(string LoanId);

Integration with Event-Driven Architecture

My implementation doesn't stop at the API level. After processing the request, we publish an event to notify other systems about the loan submission:

await loanPublisher.PublishLoanSubmittedAsync(loanCreationRequest, ct);

The message publishing interface is simple:

internal interface ILoanPublisher
{
    Task PublishLoanSubmittedAsync(SubmitLoanRequest command, CancellationToken cancellationToken);
}

And the event itself extends a base message class:

public record LoanSubmitted(string LoanId, int LoanStatus) : BaseMessage;

public abstract record BaseMessage
{
    public Guid MessageId { get; set; } = Guid.NewGuid();
    public DateTime Timestamp { get; set; } = DateTime.UtcNow;
    public string Version { get; set; } = "1.0";
}

Advantages of the REPR Pattern

1. Focused Responsibility: Each endpoint handles exactly one API operation, making the code easier to understand and maintain.

2. Improved Testability: Testing is simplified because each endpoint is focused on a single task with clear inputs and outputs.

3. Easier to Extend: Adding new endpoints doesn't require modifying existing code, adhering to the Open/Closed Principle.

4. Self-Documented API: The configuration method clearly defines the endpoint's behavior, making the API easier to understand.

5. Simplified Dependency Injection: Dependencies are injected only where needed, reducing unnecessary coupling.

6. Clean Architecture Support: This pattern fits perfectly with clean architecture and DDD principles.

Potential Improvements

Looking at my SubmitLoanEndPoint implementation, there's a TODO comment about implementing the outbox pattern:

//TODO: apply outbox pattern

This would further improve the system's resilience by ensuring that the message publishing is transactionally consistent with the database operations.

Conclusion

The REPR pattern, combined with Domain-Driven Design, has significantly improved the maintainability and scalability of my loan management system. By creating focused, single-responsibility endpoints, the code becomes more readable, testable, and extensible.

If you're struggling with bloated controllers in your API, consider giving the REPR pattern a try. Libraries like FastEndpoints make it easy to implement in .NET applications, and the benefits become increasingly apparent as your application grows.

Remember: good architecture isn't about following patterns blindly but understanding your domain's complexity and choosing patterns that help manage that complexity effectively. In my experience, the combination of DDD for the domain layer and REPR for the API layer creates a robust foundation for complex business applications.

DDD in Action: The Loan Domain Model

Looking at the code I've implemented, you can see how the loan domain takes shape through clearly defined aggregates, entities, value objects, and domain events.

Aggregates and Entities

The Loan class serves as our aggregate root, containing all the essential properties and behavior related to a loan:

internal class Loan
{
    public LoanId Id { get; private set; }
    public int LoanAmount { get; private set; }
    public int LoanTerm { get; private set; }
    public int LoanPurpose { get; private set; }
    public BankInformation BankInformation { get; private set; }
    public LoanStatus LoanStatus { get; private set; } = LoanStatus.Pending;
    public PersonalInformation PersonalInformation { get; private set; }

    private readonly List<IDomainEvent> _domainEvents = [];
    public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();
}

Notice the use of private setters and a private constructor. This encapsulation is crucial—it prevents external code from modifying the loan's state directly, preserving domain integrity.

The only way to create a loan is through the Create factory method:

public static Result<Loan> Create(LoanId Id, int LoanAmount, int LoanTerm, 
                                int LoanPurpose, LoanStatus loanStatus, 
                                PersonalInformation personalInformation, 
                                BankInformation bankInformation)
{
    var loan = new Loan(Id, LoanAmount, LoanTerm, LoanPurpose, loanStatus, 
                       personalInformation, bankInformation);

    return loan.Validate();
}

This pattern ensures that every loan instance is valid upon creation, enforcing invariants at the domain level.

Value Objects

Value objects represent descriptive aspects of the domain with no conceptual identity. In my implementation, LoanId is a perfect example of a value object:

internal record LoanId(Guid Value)
{
    public static implicit operator Guid(LoanId loanId) => loanId.Value;
    public static implicit operator LoanId(Guid value) => new(value);
}

I've leveraged C# records for value objects since they provide immutability and value-based equality out of the box. The implicit conversion operators add a nice touch, making the code more fluent when working with these types.

Rich Domain Model with Behavior

A key aspect of DDD is that domain objects encapsulate not just data but behavior. My Loan class includes methods that represent business operations:

public Result Approve()
{
    if (LoanStatus != LoanStatus.Pending)
    {
        return Result.Invalid(new ValidationError(nameof(LoanStatus), string.Empty, 
                            DomainErrors.Loan.LOAN_STATUS_INVALID, ValidationSeverity.Error));
    }

    LoanStatus = LoanStatus.Approved;
    _domainEvents.Add(new LoanApprovedEvent(Id));

    return Result.Success();
}

public Result Cancel()
{
    if (LoanStatus != LoanStatus.Pending)
    {
        return Result.Invalid(new ValidationError(nameof(LoanStatus), string.Empty, 
                            DomainErrors.Loan.LOAN_STATUS_INVALID, ValidationSeverity.Error));
    }

    LoanStatus = LoanStatus.Canceled;
    _domainEvents.Add(new LoanCanceledEvent(Id));

    return Result.Success();
}

These methods enforce business rules (a loan can only be approved if it's pending) and raise appropriate domain events, keeping the domain model self-contained and expressive.

Domain Events

Domain events play a crucial role in DDD, allowing different parts of the system to react to changes without tight coupling. Here's how I've implemented domain events:

internal abstract class LoanDomainEvent(LoanId loanId) : IDomainEvent
{
    public Guid Id { get; } = Guid.NewGuid();
    public DateTime OccurredOn { get; } = DateTime.UtcNow;
    public string EventType => GetType().Name;
    public LoanId LoanId { get; } = loanId;
}

internal class LoanApprovedEvent(LoanId loanId) : LoanDomainEvent(loanId)
{
}

internal class LoanCanceledEvent(LoanId loanId) : LoanDomainEvent(loanId)
{
}

When significant state changes occur within the domain, the relevant events are raised, allowing other components (like notification services) to act accordingly without introducing direct dependencies.

Validation as Part of the Domain

In DDD, validation belongs within the domain. Each entity and aggregate includes its own validation logic:

public Result Validate()
{
    if (Id == default)
    {
        return Result.Invalid(new ValidationError(nameof(Id), string.Empty, 
                            DomainErrors.Loan.LOAN_NOT_FOUND, ValidationSeverity.Error));
    }

    if (LoanAmount <= 0)
    {
        return Result.Invalid(new ValidationError(nameof(LoanAmount), string.Empty, 
                            DomainErrors.Loan.LOAN_AMOUNT_INVALID, ValidationSeverity.Error));
    }

    // Additional validations...

    var personalValidationResult = PersonalInformation.Validate();
    if (!personalValidationResult.IsSuccess)
    {
        return personalValidationResult.Map();
    }

    var bankValidationResult = BankInformation.Validate();
    if (!bankValidationResult.IsSuccess)
    {
        return bankValidationResult.Map();
    }

    return Result.Success();
}

This approach ensures that business rules are encapsulated within their respective domain objects and consistently applied.

The Application Layer: Command Handlers

The application layer orchestrates the domain objects to fulfill use cases. Here's how I've implemented a command handler for submitting a loan:

internal class SubmitLoanCommandHandler(ILoanRepository loanRepository) : 
    CommandHandler<SubmitLoanCommand, Result<SubmitLoanCommandResponse>>
{
    public override async Task<Result<SubmitLoanCommandResponse>> ExecuteAsync(
        SubmitLoanCommand command, CancellationToken ct = default)
    {
        // 1. Create and validate domain entities
        var personalInformationResult = PersonalInformation.Create(
            command.PersonalInformation.FullName,
            command.PersonalInformation.Email,
            command.PersonalInformation.DateOfBirth
        );

        // ... additional validation logic

        // 2. Create the aggregate root
        var loanResult = Loan.Create(
            Id: new LoanId(Guid.NewGuid()),
            LoanAmount: command.LoanAmount,
            LoanTerm: command.LoanTerm,
            LoanPurpose: command.LoanPurpose,
            loanStatus: LoanStatus.Pending,
            personalInformation: personalInformation,
            bankInformation: bankInformation);

        // ... persistence logic

        // 3. Publish domain events
        foreach (var @event in loan.DomainEvents)
        {
            var eventNotification = new LoanNotification(JsonSerializer.Serialize(@event));
            await eventNotification.PublishAsync(cancellation: ct);
        }

        return new SubmitLoanCommandResponse(loan.Id.Value.ToString());
    }
}

The command handler follows a clear workflow:

1. Create and validate domain entities

2. Create the aggregate root

3. Persist changes

4. Publish domain events

This separation ensures that application logic coordinates domain operations without mixing concerns.

Domain Events and Notifications

An important aspect of my implementation is how domain events connect to the notification system:

internal class LoanNotificationHandler : IEventHandler<LoanNotification>
{
    public Task HandleAsync(LoanNotification notification, CancellationToken cancellationToken)
    {
        // Handle the loan notification here
        // For example, send an email or push notification
        // Could apply outbox pattern here to send the notification to a queue or service bus

        return Task.CompletedTask;
    }
}

This decoupling allows the domain to focus on business rules while infrastructure components handle cross-cutting concerns like notifications.

Data Transfer Objects (DTOs) and Contracts

To separate the domain model from external contracts, I've created DTOs specifically for API communication:

public record PersonalInformationDto(string FullName, string Email, DateOnly DateOfBirth);

public record BankInformationDto(string BankName, string AccountType, string AccountNumber);

public class SubmitLoanCommand : ICommand<Result<SubmitLoanCommandResponse>>
{
    public int LoanAmount { get; set; }
    public int LoanTerm { get; set; }
    public int LoanPurpose { get; set; }
    public required BankInformationDto BankInformation { get; set; }
    public required PersonalInformationDto PersonalInformation { get; set; }
}

These DTOs define the contract between the API and clients without exposing the internal domain model.

Key Benefits of this DDD Implementation

Implementing DDD in this loan management system has provided several advantages:

1. Clear boundaries: Each domain concept has a well-defined responsibility

2. Encapsulated business rules: Validation occurs within the domain, not scattered across the application

3. Rich domain model: Entities contain both data and behavior, reflecting real-world concepts

4. Explicit state transitions: Status changes are controlled by dedicated methods that enforce business rules

5. Decoupled components: Domain events allow different parts of the system to communicate without tight coupling

Practical Considerations

While implementing DDD, I encountered several practical considerations:

Result Pattern for Error Handling

Instead of throwing exceptions, I've used the Result pattern (from Ardalis.Result) for more explicit error handling:

public Result Validate()
{
    if (string.IsNullOrEmpty(FullName))
    {
        return Result.Invalid(new ValidationError(nameof(FullName), string.Empty, 
                            DomainErrors.PersonalInformation.FULL_NAME_REQUIRED, 
                            ValidationSeverity.Error));
    }

    // Additional validations...

    return Result.Success();
}

This approach makes error paths explicit and provides a consistent way to handle validation failures.

Domain Events for Integration

Domain events provide a clean way to integrate with external systems without polluting the domain model:

// In the domain model
LoanStatus = LoanStatus.Approved;
_domainEvents.Add(new LoanApprovedEvent(Id));

// In the application layer
foreach (var @event in loan.DomainEvents)
{
    var eventNotification = new LoanNotification(JsonSerializer.Serialize(@event));
    await eventNotification.PublishAsync(cancellation: ct);
}

This approach keeps the domain model focused on business logic while allowing for integration with external systems.

Conclusion

Domain-Driven Design isn't just an academic exercise—it's a practical approach to building complex systems that reflect real business domains. By implementing DDD in this loan management system, I've created a codebase that is maintainable, testable, and aligned with business terminology.

The result is a system where:

• Business rules are clearly expressed in code

• Changes to the domain are localized and don't ripple throughout the system

• The code structure reflects the language of the domain experts

• Integration with external systems is clean and decoupled

WPF and React, and similar frameworks have been part of my journey as a developer, but now I'm immersed in the world of .NET and clean architecture principles. Many solutions I find on the web are often limited to simplistic examples that hardly reflect the challenges of real enterprise applications.

After more than a decade developing applications with different technologies, I'm surprised to see how many production implementations lack adequate separation of concerns, consisting of just a handful of folders pretending to simulate an architecture.

I've seen projects with hundreds of entities and operations all mixed together, making maintenance a nightmare. That's why I decided to implement a solution using DDD that truly separates responsibilities and maintains domain integrity.

The Problem to Solve

How can we design a loan management system that is scalable, maintainable, and accurately reflects the business rules of the financial domain?

A loan seems simple on the surface, but quickly becomes complex when we consider all the necessary validations, state management, and the need to maintain data integrity throughout the entire lifecycle of the loan.

The DDD Approach

Domain-Driven Design shines precisely in these complex scenarios. It allows us to model the domain in a way that reflects the ubiquitous language of the business and encapsulate logic in appropriate places. Let's see how I've applied several DDD patterns in my implementation.

Aggregates and Entities

In DDD, an aggregate is a set of related objects that we treat as a unit. In our case, the loan (Loan) is clearly a root aggregate that contains entities such as PersonalInformation and BankInformation.

internal class Loan
{
    public LoanId Id { get; private set; }
    public int LoanAmount { get; private set; }
    public int LoanTerm { get; private set; }
    public int LoanPurpose { get; private set; }
    public BankInformation BankInformation { get; private set; }
    public LoanStatus LoanStatus { get; private set; } = LoanStatus.Pending;
    public PersonalInformation PersonalInformation { get; private set; }

    private readonly List<IDomainEvent> _domainEvents = [];
    public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    // Private constructor to force the use of the Create method
    private Loan(LoanId Id, int LoanAmount, int LoanTerm, int LoanPurpose, 
                LoanStatus loanStatus, PersonalInformation personalInformation, 
                BankInformation bankInformation)
    {
        this.Id = Id;
        this.LoanAmount = LoanAmount;
        this.LoanTerm = LoanTerm;
        this.LoanPurpose = LoanPurpose;
        PersonalInformation = personalInformation;
        BankInformation = bankInformation;
        LoanStatus = loanStatus;
    }
}

Notice how I've designed the Loan class with private setters and a private constructor. This is a fundamental principle: encapsulation. We can only create a loan through the Create method (Factory pattern):

public static Result<Loan> Create(LoanId Id, int LoanAmount, int LoanTerm, 
                                int LoanPurpose, LoanStatus loanStatus, 
                                PersonalInformation personalInformation, 
                                BankInformation bankInformation)
{
    var loan = new Loan(Id, LoanAmount, LoanTerm, LoanPurpose, loanStatus, 
                      personalInformation, bankInformation);

    return loan.Validate();
}

Value Objects

Value Objects are another crucial component of DDD. They are immutable and identified by the value of their properties, not by an identity. In my implementation, LoanId is a perfect example:

internal record LoanId(Guid Value)
{
    public static implicit operator Guid(LoanId loanId) => loanId.Value;
    public static implicit operator LoanId(Guid value) => new(value);
}

I'm using modern C# here with records, which are ideal for Value Objects due to their immutable nature.

Domain Rules and Validations

One of the most important parts of DDD is ensuring that business rules are in the right place: within the domain. I've incorporated validations directly into the entities:

public Result Validate()
{
    if (Id == default)
    {
        return Result.Invalid(new ValidationError(nameof(Id), string.Empty, 
                            DomainErrors.Loan.LOAN_NOT_FOUND, ValidationSeverity.Error));
    }

    if (LoanAmount <= 0)
    {
        return Result.Invalid(new ValidationError(nameof(LoanAmount), string.Empty, 
                            DomainErrors.Loan.LOAN_AMOUNT_INVALID, ValidationSeverity.Error));
    }

    // More validations...

    var personalValidationResult = PersonalInformation.Validate();
    if (!personalValidationResult.IsSuccess)
    {
        return personalValidationResult.Map();
    }

    var bankValidationResult = BankInformation.Validate();
    if (!bankValidationResult.IsSuccess)
    {
        return bankValidationResult.Map();
    }

    return Result.Success();
}

Domain Events

Domain events are fundamental to correctly implementing DDD, especially in complex systems. They allow decoupling certain actions and facilitate implementing patterns like CQRS.

internal abstract class LoanDomainEvent(LoanId loanId) : IDomainEvent
{
    public Guid Id { get; } = Guid.NewGuid();
    public DateTime OccurredOn { get; } = DateTime.UtcNow;
    public string EventType => GetType().Name;
    public LoanId LoanId { get; } = loanId;
}

internal class LoanApprovedEvent(LoanId loanId) : LoanDomainEvent(loanId)
{
}

internal class LoanCanceledEvent(LoanId loanId) : LoanDomainEvent(loanId)
{
}

And in the loan entity, we use these events when important changes occur:

public Result Approve()
{
    if (LoanStatus != LoanStatus.Pending)
    {
        return Result.Invalid(new ValidationError(nameof(LoanStatus), string.Empty, 
                            DomainErrors.Loan.LOAN_STATUS_INVALID, ValidationSeverity.Error));
    }

    LoanStatus = LoanStatus.Approved;
    _domainEvents.Add(new LoanApprovedEvent(Id));

    return Result.Success();
}

Nested Entities

The loan contains entities such as PersonalInformation and BankInformation. These entities also have their own encapsulated validations:

internal class PersonalInformation
{
    public string FullName { get; private set; }
    public string Email { get; private set; }
    public DateOnly DateOfBirth { get; private set; }

    private PersonalInformation(string fullName, string email, DateOnly dateOfBirth)
    {
        FullName = fullName;
        Email = email;
        DateOfBirth = dateOfBirth;
    }

    public static Result<PersonalInformation> Create(string fullName, string email, DateOnly dateOfBirth)
    {
        var personalInformation = new PersonalInformation(fullName, email, dateOfBirth);
        return personalInformation.Validate();
    }

    public Result Validate()
    {
        if (string.IsNullOrEmpty(FullName))
        {
            return Result.Invalid(new ValidationError(nameof(FullName), string.Empty, 
                                DomainErrors.PersonalInformation.FULL_NAME_REQUIRED, 
                                ValidationSeverity.Error));
        }

        // More validations...

        return Result.Success();
    }
}

Advantages of this Approach

1. Robust encapsulation: Entities control their internal states

2. Protected business rules: Validation occurs within the domain

3. Ubiquitous language: The code reflects business terms

4. Maintainability: Changes in the domain are localized

5. Testability: It's easy to test entities and their behaviors

Important Points to Highlight

1. Private Constructors and Factory Methods

Note that all constructors are private. This forces us to use the Create methods that include validation. It's impossible to create an invalid object.

2. Error Handling with Result

Instead of throwing exceptions, I'm using the Result pattern (from the Ardalis.Result library) which offers a more explicit and predictable way of handling errors:

public Result<PersonalInformation> Create(string fullName, string email, DateOnly dateOfBirth)
{
    var personalInformation = new PersonalInformation(fullName, email, dateOfBirth);
    return personalInformation.Validate();
}

3. Controlled State Transitions

Loan state changes are controlled by specific methods, not by public setters:

public Result Approve()
{
    if (LoanStatus != LoanStatus.Pending)
    {
        return Result.Invalid(new ValidationError(nameof(LoanStatus), string.Empty, 
                            DomainErrors.Loan.LOAN_STATUS_INVALID, ValidationSeverity.Error));
    }

    LoanStatus = LoanStatus.Approved;
    _domainEvents.Add(new LoanApprovedEvent(Id));

    return Result.Success();
}

Conclusion

Implementing DDD is not simply adopting a set of technical patterns; it's a mindset shift. It's about modeling software to reflect the real business domain, not the other way around.

In my experience, although this approach may initially seem more complex and verbose compared to typical CRUD examples found online, it pays enormous dividends when the application grows in complexity, especially for enterprise applications with numerous intertwined business rules.

The real benefits include:

• Clear separation of concerns

• Testable business logic independent of infrastructure

• Code that reflects the business language

• Validations contained in the right place

• Easy to extend without breaking domain integrity

As developers, it's easy to fall into the trap of thinking only in terms of technology and frameworks. DDD reminds us that our main goal is to solve business problems, and that code should reflect the domain we're modeling.

The next time you face a complex problem, consider whether DDD might be the answer. It's not a silver bullet, but for domains rich in business rules like financial loans, few architectures offer such a clear and maintainable approach.

There are countless topics to cover when discussing MVVM, especially when using TypeScript, because there's essentially no documentation or examples for this approach in the TypeScript ecosystem.

In this blog, I'll gradually try to change that. Although this blog is primarily for .NET developers, TypeScript is essential in my stack for frontend development, so I'll also cover many aspects of it as I work on different applications.

Problem to Solve

In the previous post, we built a Stepper where each step has its own View and ViewModel. So far so good, but this approach presents several challenges:

• How can I access the data from each ViewModel to build the request that we'll send to the backend?

• How can I determine if any ViewModel is in an invalid state?

• How can I add more ViewModels to the Stepper without affecting the existing logic?

• How can I change their order?

• How can I remove them if necessary?

As you can see, dear reader, there are quite a few scenarios we need to cover if we want our Stepper to be flexible, scalable, and above all, maintainable in the long term.

The Solution: Parent ViewModel

To solve this problem, we'll use a concept called the Parent ViewModel.

What is a Parent ViewModel?

As the name suggests, it's a ViewModel that acts as an orchestrator. Its job is to read the list of ViewModels that the Stepper will have and dynamically display them in the UI.

The child ViewModels (each section of the Stepper) don't know how they're being used and have no idea that other ViewModels exist. They are completely isolated, following principles of composition. This way, we can build components in a Lego-like fashion, block by block.

To achieve this, we first need to have a list of the ViewModels we want to display in our Stepper.

I've created a registry where we'll indicate the list of ViewModels we want to deploy in our Stepper:

import type { IStepViewModel } from "~/interfaces/IStepViewModel";
import { PersonalInformationViewModel } from "~/viewModels/personalInformationViewModel";
import { LoanDetailsViewModel } from "~/viewModels/loanDetailsViewModel";
import { BankInformationViewModel } from "~/viewModels/bankInformationViewModel";
import PersonalInformationView from "~/views/personalInformationView";
import LoanDetailsView from "~/views/loanDetailsView";
import BankInformationView from "~/views/bankInformationView";

type StepRegistry = {
  [key: string]: {
    viewModelClass: new () => IStepViewModel<any>;
    component: React.ComponentType<{ viewModel: IStepViewModel<any> }>;
  };
};

export const stepRegistry: StepRegistry = {
  personalInfo: {
    viewModelClass: PersonalInformationViewModel,
    component: PersonalInformationView,
  },
  loanDetails: {
    viewModelClass: LoanDetailsViewModel,
    component: LoanDetailsView,
  },
  bankInfo: {
    viewModelClass: BankInformationViewModel,
    component: BankInformationView,
  },
};

This registry serves as a central configuration point for our Stepper. Each entry maps a unique key to an object containing both the ViewModel class and its corresponding View component. This approach provides several advantages:

1. It decouples the definition of our steps from their implementation

2. It makes the order of steps explicit and easily modifiable

3. It allows for dynamic step management (adding, removing, or reordering steps)

Standardizing ViewModel Structure

To standardize the structure of the ViewModels and make it easy for the Parent ViewModel and UI to access the required information from all ViewModels, I've created new interfaces and extended the functionality of some existing ones.

IViewModel

This generic interface has been extended where T is the object we're going to validate. The concept is straightforward:

import { Observable } from "rxjs";
import type { IValidationError } from "./IValidationError";

export interface IViewModel<T> {
  data$: Observable<T>;
  errors$: Observable<IValidationError[]>;
  updateData(data: Partial<T>): void;
  validate(): void;
}

The interface uses RxJS observables to expose reactive streams of both the data and validation errors. This reactive approach is central to the MVVM pattern, allowing the View to automatically update when the underlying data or validation state changes. The updateData method allows for partial updates to the model, while validate triggers validation of the current state.

IValidationError

This interface indicates the structure our validation errors will have:

export interface IValidationError {
  field: string;
  message: string;
}

By standardizing our validation errors with a consistent structure, we enable uniform error handling across all ViewModels. The field property identifies which specific field has the error, while the message provides user-friendly information about the validation failure.

IStepViewModel

This interface is a marker that will help the Parent ViewModel identify the different ViewModels that will be deployed in the Stepper:

import type { IViewModel } from "./IViewModel";

export interface IStepViewModel<T> extends IViewModel<T> {
}

While this interface doesn't add additional methods, it serves an important architectural purpose by clearly indicating which ViewModels are designed to work as steps in our Stepper. This kind of type-based classification enhances code readability and maintainability.

Parent ViewModel Implementation

The Parent ViewModel reads the ViewModel registry, creates an instance of each ViewModel (we could use dependency injection to construct the ViewModel), and can move steps forward, backward, and get the current ViewModel.

The Parent ViewModel persists the instance of each of the ViewModels to prevent React from creating new instances of them on each render:

import { BehaviorSubject, Observable } from "rxjs";
import { map } from "rxjs/operators";
import { stepRegistry } from "~/helpers/stepRegistry";
import type { IStepViewModel } from "~/interfaces/IStepViewModel";

export class ParentViewModel {
  private viewModels: Array<IStepViewModel<any>> = [];
  private currentStepSubject = new BehaviorSubject<number>(0);

  public currentStep$ = this.currentStepSubject.asObservable();
  public currentViewModel$: Observable<IStepViewModel<any>>;

  constructor() {
    // we could use DI to inject the view models, but for now we'll just use the registry
    this.viewModels = Object.values(stepRegistry).map((entry) => new entry.viewModelClass());
    this.currentViewModel$ = this.currentStep$.pipe(
      map((step) => this.viewModels[step])
    );
  }

  nextStep(): void {
    const currentStep = this.currentStepSubject.value;
    if (currentStep < this.viewModels.length - 1) {
      this.currentStepSubject.next(currentStep + 1);
    }
  }

  previousStep(): void {
    const currentStep = this.currentStepSubject.value;
    if (currentStep > 0) {
      this.currentStepSubject.next(currentStep - 1);
    }
  }

  getCurrentStep(): number {
    return this.currentStepSubject.value;
  }

  getViewModel(step: number): IStepViewModel<any> | undefined {
    return this.viewModels[step];
  }
}

The Parent ViewModel uses RxJS's BehaviorSubject to maintain the current step index and expose it as an observable. This reactive approach allows components to subscribe to step changes and automatically update when the step changes.

Another key implementation detail is the currentViewModel$ observable, which provides a stream of the current ViewModel based on the current step. This makes it easy for the View to always have access to the appropriate ViewModel without having to manually determine which one is active.

Parent View Implementation

The Parent View persists the instance of Parent ViewModel using useRef. Thanks to this, we'll have only one instance of this ViewModel and, in turn, one instance of each ViewModel in the Stepper, thus preventing React from creating a new instance on each render.

This component subscribes to the currentStep$ property at the component's initialization:

useEffect(() => {
  subscription = parentViewModel.currentStep$.subscribe((step) => {
    setCurrentStep(step);
  });

  return () => {
    if (subscription) {
      subscription.unsubscribe();
    }
  };
}, []);

Here's where the magic happens:

As the user moves through the Stepper, we obtain the ViewModel that corresponds to each step:

const currentEntry = Object.values(stepRegistry)[currentStep];
const CurrentComponent = currentEntry.component;
const currentViewModel = parentViewModel.getViewModel(currentStep);

Finally, we render the Component:

<CurrentComponent viewModel={currentViewModel} />

Benefits of This Approach

With this technique, to add, remove, or change ViewModels, all I have to do is go to the registry and modify the ViewModels that will be displayed. This provides exceptional flexibility without having to touch the core implementation of the Stepper component.

I could even extend the registry to also be a ViewModel and dynamically add ViewModels using dependency injection or some other strategy.

The separation of concerns here is particularly strong:

1. Each ViewModel handles only its own data and validation logic

2. The Parent ViewModel orchestrates the flow between steps without knowing the details of each step

3. The Views focus solely on rendering the UI based on the ViewModel state

4. The registry serves as a centralized configuration point

This approach also makes testing much easier, as each component can be tested in isolation.

Conclusion

The Parent ViewModel pattern offers a powerful solution for complex multi-step interfaces in React applications. By leveraging TypeScript's type system and the principles of the MVVM pattern, we can create highly modular, maintainable, and extensible components.

This approach particularly shines in enterprise applications where forms may need to evolve over time, with steps being added, removed, or reordered. The registry-based configuration makes these changes trivial, without requiring changes to the core implementation.

Windows Presentation Foundation, without fear of being wrong, is the father of MVVM, so to speak, as this pattern and the concept of data binding were introduced with this framework.

I was truly amazed by this UI framework when I had the opportunity to attend a Telerik conference where they showcased their UI components with WPF.

WPF was (and still is) very powerful, and what caught my attention was how the project in the presentation was structured, where the UI was completely empty (without codebehind). I was already familiar with MVVM, but it wasn't until that moment when I decided to deepen my knowledge of this pattern.

After many years making XAML apps for WPF, Silverlight, UWP with MVVM, times change, and I ventured into the world of TypeScript with React. Surprisingly, I realized that very few or almost no one, at least publicly, uses MVVM with this UI framework.

All the examples I found (and still find) are projects with a basic structure that honestly leaves much to be desired, as their level of separation of concerns is limited to the use of folders.

After developing desktop apps for more than a decade, I realized that in the web world, adopting these practices was relatively rare for web developers. Additionally, at the JavaScript/TypeScript level, I saw terrible practices (I still see them) when watching YouTubers and example code.

Although I understand they are examples, I would be quite concerned if these practices are carried over to enterprise-level applications (I fear that is the case).

That's why I decided to create a repository that uses a template for my personal projects as a base:

SrRickGrimes/SaaS-Template-V2

This repository only contains the skeleton of the projects I develop and I don't intend to touch on it in this article.

As I mentioned before, using this repository as a base, I've created a simple demo where I show patterns used in enterprise-level applications. You might say that some applied patterns are too much for the scenario, but the objective is to show how they are applied. It will be up to you whether to apply them depending on your requirements.

Let's Begin by Explaining the Problem to Solve

The best scenario I found is a banking loan app, where typically the fields to fill out are endless. I've seen applications with up to 1,000 properties divided among 60 or 70 forms.

The question is: how could we develop an app that is scalable, maintainable, and easy to understand?

This is where MVVM shines by itself, as it was created for these complex scenarios where we require a clear separation of responsibilities. By applying some advanced techniques, we can have a clean solution, and although it may grow over time, the technical debt will be manageable.

The Requirements

The requirements are basic. We need to create a Stepper where this stepper can have n forms. These forms can change order or no longer be required as time passes, or we can also add more.

If we think about it in React style, I can already imagine using React Context with some other State framework, etc., which could make sense. But the key here is that the business logic and everything we write in our forms should be agnostic of React. This principle is very useful, especially in a JavaScript ecosystem where a new framework comes out every weekend. Today it's React, next month it's Vue, and the month after that, it's Svelte or some other.

The JavaScript ecosystem is very unstable, so it's extremely important that enterprise applications and their business rules are decoupled from the UI of the moment.

What is MVVM?

MVVM stands for Model - View - ViewModel

Model

In simple words, the Model is our class with properties to encapsulate the data of our app, generally POCOs. These models are typically used with services, repositories, etc.

ViewModel

The ViewModel implements properties and commands with which the view can connect through data binding, and it notifies the view of any state change that occurs through notification events.

The commands provide functionality that the UI can use to determine the functionality that will be displayed in the UI.

View

The view is responsible for defining the structure, layout, and appearance of what the user sees on the screen. It does not contain business logic; however, in some cases, it could contain code-behind specific to the UI framework used, such as animations.

There is extensive documentation and many examples for .NET with WPF/UWP and other XAML-based frameworks.

To my surprise, the examples I found in TypeScript are very few or too basic, or in my humble opinion, they don't follow the principles of MVVM because they add UI functionalities within the ViewModels, breaking several principles.

The Loan Manager Wizard Components

The Loan Manager Wizard consists of several sections:

1. Personal Information: Client's personal information

2. Bank Information: Bank information

3. Loan Details: Loan details

BankInformation Model

import { BehaviorSubject } from "rxjs";

export class BankInformation {
  private bankNameSubject = new BehaviorSubject<string>("");
  private accountTypeSubject = new BehaviorSubject<string>("");
  private accountNumberSubject = new BehaviorSubject<string>("");

  public bankName$ = this.bankNameSubject.asObservable();
  public accountType$ = this.accountTypeSubject.asObservable();
  public accountNumber$ = this.accountNumberSubject.asObservable();

  constructor(data?: { bankName?: string; accountType?: string; accountNumber?: string }) {
    if (data?.bankName) this.bankNameSubject.next(data.bankName);
    if (data?.accountType) this.accountTypeSubject.next(data.accountType);
    if (data?.accountNumber) this.accountNumberSubject.next(data.accountNumber);
  }

  setBankName(bankName: string): void {
    this.bankNameSubject.next(bankName);
  }

  setAccountType(accountType: string): void {
    this.accountTypeSubject.next(accountType);
  }

  setAccountNumber(accountNumber: string): void {
    this.accountNumberSubject.next(accountNumber);
  }

  get bankName(): string {
    return this.bankNameSubject.value;
  }

  get accountType(): string {
    return this.accountTypeSubject.value;
  }

  get accountNumber(): string {
    return this.accountNumberSubject.value;
  }
}

LoanDetails Model

import { BehaviorSubject } from "rxjs";

export class LoanDetails {
  private loanAmountSubject = new BehaviorSubject<number>(0);
  private loanTermSubject = new BehaviorSubject<number>(0);
  private loanPurposeSubject = new BehaviorSubject<number>(0);

  public loanAmount$ = this.loanAmountSubject.asObservable();
  public loanTerm$ = this.loanTermSubject.asObservable();
  public loanPurpose$ = this.loanPurposeSubject.asObservable();

  constructor(data?: { loanAmount?: number; loanTerm?: number; loanPurpose?: number }) {
    if (data?.loanAmount) this.loanAmountSubject.next(data.loanAmount);
    if (data?.loanTerm) this.loanTermSubject.next(data.loanTerm);
    if (data?.loanPurpose) this.loanPurposeSubject.next(data.loanPurpose);
  }

  setLoanAmount(loanAmount: number): void {
    this.loanAmountSubject.next(loanAmount);
  }

  setLoanTerm(loanTerm: number): void {
    this.loanTermSubject.next(loanTerm);
  }

  setLoanPurpose(loanPurpose: number): void {
    this.loanPurposeSubject.next(loanPurpose);
  }

  get loanAmount(): number {
    return this.loanAmountSubject.value;
  }

  get loanTerm(): number {
    return this.loanTermSubject.value;
  }

  get loanPurpose(): number {
    return this.loanPurposeSubject.value;
  }
}

PersonalInformation Model

import { BehaviorSubject } from "rxjs";

export class PersonalInformation {
  private fullNameSubject = new BehaviorSubject<string>('');
  private dateOfBirthSubject = new BehaviorSubject<string>('');
  private emailSubject = new BehaviorSubject<string>('');

  public fullName$ = this.fullNameSubject.asObservable();
  public dateOfBirth$ = this.dateOfBirthSubject.asObservable();
  public email$ = this.emailSubject.asObservable();

  constructor(data?: { fullName?: string; dateOfBirth?: string; email?: string }) {
    if (data?.fullName) this.fullNameSubject.next(data.fullName);
    if (data?.dateOfBirth) this.dateOfBirthSubject.next(data.dateOfBirth);
    if (data?.email) this.emailSubject.next(data.email);
  }

  get fullName(): string {
    return this.fullNameSubject.value;
  }

  get dateOfBirth(): string {
    return this.dateOfBirthSubject.value;
  }

  get email(): string {
    return this.emailSubject.value;
  }

  setFullName(fullName: string): void {
    this.fullNameSubject.next(fullName);
  }

  setDateOfBirth(dateOfBirth: string): void {
    this.dateOfBirthSubject.next(dateOfBirth);
  }

  setEmail(email: string): void {
    this.emailSubject.next(email);
  }
}

If you review the models, dear reader, you will have noticed that I'm using RxJs. This library is in charge of helping us with the notifications that our model needs to make to know that its state has changed.

In .NET with WPF, we have the INotifyPropertyChanged interface, and WPF and XAML-based apps (also Blazor) include Binding out of the box.

For our manager, we have to do it manually, that's why I'm using RxJs.

The code for the models shouldn't be complex to understand as we only have some observables for each property with its getter and setter.

Writing the ViewModel

In this case, the ViewModels of each section of the Stepper have a main function, which is to validate that the model is always in a Valid state.

import { BehaviorSubject, combineLatest, Observable } from "rxjs";
import { map, debounceTime } from "rxjs/operators";
import type { IStepViewModel } from "~/interfaces/IStepViewModel";
import type { IValidationError } from "~/interfaces/IValidationError";
import { BankInformation } from "~/models/bankInformation";
import { AccountNumberFormatByTypeSpecification } from "~/specifications/BankInformationSpecifications/AccountNumberFormatByTypeSpecification";
import { AccountNumberSpecification } from "~/specifications/BankInformationSpecifications/AccountNumberSpecification";
import { AccountTypeSpecification } from "~/specifications/BankInformationSpecifications/AccountTypeSpecification";
import { BankNameSpecification } from "~/specifications/BankInformationSpecifications/BankNameSpecification";
import type { ISpecification } from "~/specifications/ISpecification";

export class BankInformationViewModel implements IStepViewModel<BankInformation> {
  private model: BankInformation;
  private _errors: BehaviorSubject<IValidationError[]>;
  private formSpecification: ISpecification<BankInformation>;

  public data$: Observable<BankInformation>;
  public errors$: Observable<IValidationError[]>;
  public isValid$: Observable<boolean>;

  constructor() {
    this.model = new BankInformation();
    this._errors = new BehaviorSubject<IValidationError[]>([]);

    // Create individual specifications
    const bankNameSpec = new BankNameSpecification();
    const accountTypeSpec = new AccountTypeSpecification();
    const accountNumberSpec = new AccountNumberSpecification();
    const accountNumberFormatSpec = new AccountNumberFormatByTypeSpecification();

    // Combine specifications for the whole form
    this.formSpecification = bankNameSpec
      .and(accountTypeSpec)
      .and(accountNumberSpec)
      .and(accountNumberFormatSpec);

    // Set up data observable
    this.data$ = combineLatest([
      this.model.bankName$,
      this.model.accountType$,
      this.model.accountNumber$,
    ]).pipe(
      map(([bankName, accountType, accountNumber]) => {
        return new BankInformation({ bankName, accountType, accountNumber });
      })
    );

    // Set up errors observable
    this.errors$ = this._errors.asObservable();

    // Set up validity observable
    this.isValid$ = this.errors$.pipe(
      map(errors => errors.length === 0)
    );

    // Set up automatic validation when data changes
    this.data$.pipe(
      debounceTime(300) // Wait 300ms after the last change before validating
    ).subscribe(() => {
      this.validate();
    });

    // Run initial validation
    this.validate();
  }

  updateData(data: Partial<BankInformation>): void {
    if (data.bankName !== undefined) this.model.setBankName(data.bankName);
    if (data.accountType !== undefined) this.model.setAccountType(data.accountType);
    if (data.accountNumber !== undefined) this.model.setAccountNumber(data.accountNumber);
  }

  updateBankName(bankName: string): void {
    this.model.setBankName(bankName);
  }

  updateAccountType(accountType: string): void {
    this.model.setAccountType(accountType);
  }

  updateAccountNumber(accountNumber: string): void {
    this.model.setAccountNumber(accountNumber);
  }

  validate(): void {
    // Use the check method from the combined specification
    const validationResult = this.formSpecification.check(this.model);
    // Map validation errors to the expected format
    const errors: IValidationError[] = validationResult.errors.map(error => ({
      field: error.field,
      message: error.message
    }));
    // Update the errors subject
    this._errors.next(errors);
  }
}

As you will see, the ViewModel offers 3 key properties:

1. Data: The model used by the ViewModel and where we can access the information created by the user.

2. Errors: The list of validation errors produced by the ViewModel, and these validations will be shown in the UI.

3. IsValid: If the ViewModel is in a valid state.

If you look more closely, I have implemented the specification pattern to validate each form.

I don't intend to go into details about what the specification pattern is and what it's used for.

But thanks to this, we can encapsulate the validation logic in different classes, removing that responsibility from the ViewModel (following SOLID principles).

Here is a specification example:

import { ValidationResult } from "~/helpers/validationResult";
import type { BankInformation } from "~/models/bankInformation";
import { Specification } from "../Specification";

export class BankNameSpecification extends Specification<BankInformation> {
  constructor(private minLength: number = 2) {
    super();
  }

  isSatisfiedBy(candidate: BankInformation): boolean {
    return candidate.bankName.length >= this.minLength;
  }

  check(candidate: BankInformation): ValidationResult {
    if (!candidate.bankName || candidate.bankName.trim().length === 0) {
      return ValidationResult.invalid('bankName', 'Bank name is required');
    }

    if (candidate.bankName.length < this.minLength) {
      return ValidationResult.invalid('bankName', `Bank name must be at least ${this.minLength} characters`);
    }

    return ValidationResult.valid();
  }
}

As you can see, the implementation is very simple and easy to understand, without using third-party libraries or dependencies, purely applying MVVM and following the principle that our implementation should be agnostic of the UI. That's the main reason I've opted for specifications.

Now, using Fluent Specifications design (Fluent API Design Pattern), we can combine the specifications to validate the entire form:

this.formSpecification = bankNameSpec
  .and(accountTypeSpec)
  .and(accountNumberSpec)
  .and(accountNumberFormatSpec);

Finally, in our Validate method, we call our formSpecification, and it will validate the entire form, and we only update the errors collection with the errors produced:

validate(): void {
  // Use the check method from the combined specification
  const validationResult = this.formSpecification.check(this.model);
  // Map validation errors to the expected format
  const errors: IValidationError[] = validationResult.errors.map(error => ({
    field: error.field,
    message: error.message
  }));
  // Update the errors subject
  this._errors.next(errors);
}

Connecting the View with the ViewModel

This React component is only subscribing to the notifications produced by Data from our ViewModel. Using React's useState, every time a change is produced, we update the bankInfo object, and this propagates the changes in the form components using normal React:

import { useEffect, useState, type FC } from "react";
import type { IStepViewModel } from "~/interfaces/IStepViewModel";
import type { IValidationError } from "~/interfaces/IValidationError";
import { BankInformation } from "~/models/bankInformation";

interface BankInformationViewProps {
  viewModel: IStepViewModel<BankInformation>;
}

const BankInformationView: FC<BankInformationViewProps> = ({ viewModel }) => {
  const [bankInfo, setBankInfo] = useState<BankInformation>(new BankInformation());
  const [errors, setErrors] = useState<IValidationError[]>([]);

  useEffect(() => {
    // Subscribe to data changes
    const dataSubscription = viewModel.data$.subscribe((info) => {
      setBankInfo(info);
    });
    // Subscribe to validation errors
    const errorsSubscription = viewModel.errors$.subscribe((validationErrors) => {
      setErrors(validationErrors);
    });

    // Force an initial validation
    if (typeof viewModel.validate === 'function') {
      viewModel.validate();
    }

    return () => {
      dataSubscription.unsubscribe();
      errorsSubscription.unsubscribe();
    };
  }, [viewModel]);

  // Helper function to get error for a specific field
  const getFieldError = (fieldName: string): string | null => {
    const error = errors.find(e => e.field === fieldName);
    return error ? error.message : null;
  };

  const handleBankNameChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    viewModel.updateData({ bankName: e.target.value });
  };

  const handleAccountTypeChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
    viewModel.updateData({ accountType: e.target.value });
  };

  const handleAccountNumberChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    viewModel.updateData({ accountNumber: e.target.value });
  };

  return (
    <div className="space-y-4">
      <h2 className="text-xl font-semibold">Bank Information</h2>
      {/* Bank Name Field */}
      <div className="form-control">
        <label className="label">
          <span className="label-text">Bank Name</span>
        </label>
        <input
          type="text"
          placeholder="Bank Name"
          value={bankInfo.bankName}
          onChange={handleBankNameChange}
          className={`input input-bordered w-full ${getFieldError('bankName') ? 'border-red-500' : ''}`}
        />
        {getFieldError('bankName') && (
          <div className="text-red-500 text-sm mt-1">{getFieldError('bankName')}</div>
        )}
      </div>
      {/* Account Type Field */}
      <div className="form-control">
        <label className="label">
          <span className="label-text">Account Type</span>
        </label>
        <select
          value={bankInfo.accountType}
          onChange={handleAccountTypeChange}
          className={`select select-bordered w-full ${getFieldError('accountType') ? 'border-red-500' : ''}`}
        >
          <option value="">Select account type</option>
          <option value="checking">Checking</option>
          <option value="savings">Savings</option>
          <option value="credit">Credit</option>
        </select>
        {getFieldError('accountType') && (
          <div className="text-red-500 text-sm mt-1">{getFieldError('accountType')}</div>
        )}
      </div>
      {/* Account Number Field */}
      <div className="form-control">
        <label className="label">
          <span className="label-text">Account Number</span>
        </label>
        <input
          type="text"
          placeholder="Account Number"
          value={bankInfo.accountNumber}
          onChange={handleAccountNumberChange}
          className={`input input-bordered w-full ${getFieldError('accountNumber') ? 'border-red-500' : ''}`}
        />
        {getFieldError('accountNumber') && (
          <div className="text-red-500 text-sm mt-1">{getFieldError('accountNumber')}</div>
        )}
        <div className="text-gray-500 text-xs mt-1">
          {bankInfo.accountType === 'checking' && 'Checking accounts must start with 4 or 5'}
          {bankInfo.accountType === 'savings' && 'Savings accounts must start with 1 or 2'}
          {bankInfo.accountType === 'credit' && 'Credit accounts must start with 9'}
        </div>
      </div>
    </div>
  );
};

export default BankInformationView;

As you can see, MVVM is a very powerful pattern, and highly scalable and maintainable apps can be developed as long as the principles are followed correctly.

In the next article, I will cover other aspects of the same repository that are not mentioned in this article.

Here is the repository where you can find the implementation: SrRickGrimes/SaaS-Template-V2

Conclusion

The MVVM pattern, originally popularized in the desktop application world with WPF, can be successfully applied to modern web development with React. By keeping our business logic agnostic from the UI framework and using advanced patterns like Specification for validation, we can build scalable applications that are easier to maintain over time. The key benefits include:

1. Clear separation of concerns

2. Testable business logic independent of UI

3. Reactive state management with RxJs

4. Composable validation using the Specification pattern

5. UI framework independence for core business rules

While this approach might seem more complex initially compared to typical React examples found online, it pays dividends as the application grows in complexity, especially for enterprise applications with numerous forms and complex validation rules.

Rather than just sitting down to write code and imagining this CRM—which is the most comfortable thing a software engineer can do, locking themselves in their bubble and spending months or years building something nobody will use or pay for—I took a different path.

I decided to learn even more about startups and modern techniques in this field, as my first interaction with entrepreneurship was back in 2010 when I attended an event for entrepreneurs.

Back then, the proposal was to create an MVP (Minimum Viable Product) and test it with customers interactively. While it sounds good in theory, based on my experience, I realized this might no longer apply.

Developing applications isn't as difficult as it used to be because technology keeps advancing—things like artificial intelligence and now these new "vibe coders"... who claim they can make apps (I'll talk about this topic in another post and explain why I think now more than ever we need engineers who know how to develop software).

So I decided to explore the topic further and found Rob Walling's channel [MicroConf](https://youtube.com/@microconf?si=9hAF-1phA-macfVv).

I watched all the videos from this content creator, and honestly, it changed my thinking about startups and the ideas I had about them since 2010.

Key Insights

Some phrases that stuck with me after watching his videos:

"There are problems not worth solving."

"Instead of telling me your idea, tell me the problem you want to solve."

After analyzing and studying entrepreneurship again, I realized several things.

Code and its quality, although important, ultimately don't matter because customers only focus on whether it solves their problem, is stable, and provides a good user experience.

This last point short-circuited my way of thinking because, having been a software architect for many years, I always focused on the technical aspects of the product but had never focused on what the customer wants from their perspective and is willing to pay for.

Getting My Hands Dirty with Research

So I took on the task of contacting different companies and startups that use WhatsApp as their main point of access to customers and businesses. I spent time taking notes, even from many who were already using solutions like LeadSales and Kommo.

The list of problems was significant, and within this list, common issues emerged. These are where I concentrated to start planning the main features that together would solve my potential customers' problems.

Real Problems I Identified

Here are some of the problems I managed to identify:

• Many existing applications don't offer a UX designed with the user in mind, requiring people to take courses to understand how they work.

• Lack of preview for incoming messages, which means users have to open the chat to see them.

• Very basic chat organization model; even though LeadSales offers funnels, the features are very basic.

• Lack of metrics that actually serve the business; it's not valuable for many to just indicate how many messages have been received.

• The bots offered by some platforms are very basic.

And I could continue with many more problems that were mentioned to me.

What's Next?

In the next article, I'll broadly explain what features the CRM will provide in its first version and how this has been validated interactively with a feedback loop.

My Takeaway

Look, I've been in this game a while, and the biggest shift in my thinking has been moving from "what cool tech can I build?" to "what problems can I actually solve?"

Talking to real businesses using WhatsApp has been eye-opening. These folks are struggling with clunky interfaces, spending way too much time managing conversations, and missing opportunities because their tools just aren't cutting it.

The irony is that while I was obsessing over architecture decisions and code quality (which I still love, don't get me wrong), most users couldn't care less about my beautiful microservices or elegant code patterns. They just want something that makes their work easier and helps them close more deals.

This research phase has completely transformed how I'm approaching this CRM. Instead of building what I think is cool, I'm building what I know solves real headaches for real businesses. And honestly? That's way more satisfying than showing off some fancy tech stack that nobody appreciates.

Stay tuned for the next post where I'll break down exactly what this WhatsApp CRM will do and how each feature directly addresses the pain points I discovered during my conversations with potential users.

When I decided to create a WhatsApp CRM, I began researching existing apps from a technical perspective to understand their challenges and how difficult WhatsApp integration would be.

Fortunately, I found a video from the entrepreneurs behind LeadSales platform where they explained the technical challenges they've faced (I'm not sure if they still have these issues).

What caught my attention most was their scalability challenge. In their video, they mentioned handling 70 million messages per month—a considerable volume—and were experiencing scalability problems.

This is where I thought: they're already established with many users, and any entrepreneur would tell you to build an MVP to test the market first, or create a prototype.

However, in this case, they had already done that research for me, validating the market. According to various entrepreneurship books I've read, you either find a "blue ocean" (extremely rare these days) or enter to compete. I chose the latter, only verifying the market wasn't as saturated as others like note-taking apps, personal finance apps, video games, etc.

The first challenge they presented was scaling. Many engineers' natural response is microservices—the trend for the past 10 years. But as I've said before and will continue saying, 99% of cases don't require microservices. In practice, I see many disadvantages which I won't detail here (perhaps in another article).

Ten years ago, I had the opportunity to meet the development team behind Microsoft Orleans, a framework powering Microsoft services like Office 365, Xbox Live, and games like Halo and Gears of War.

For these reasons, I chose a more pragmatic and simple approach to solve the problem.

A modular architecture (Modular Monolith) with Microsoft Orleans is the perfect solution for this scenario.

Let's Talk Tech

Look, when I mention Microsoft Orleans, I'm talking about this cool actor-based framework that makes distributed systems way less painful. Instead of building dozens of separate services that need to talk to each other through complex APIs and message queues, Orleans gives you these things called "virtual actors" that just handle their business automatically across your servers. It's like getting all the scaling benefits without the massive headache.

And this Modular Monolith approach? It's basically having your cake and eating it too. You deploy one application (simple!) but organize it internally into clean, separated modules (organized!). I've seen too many teams jump straight to microservices without realizing what they're signing up for.

The Microservices Trap

I can't tell you how many projects I've seen where teams went full microservices way too early. The data backs this up too. I was reading that something like 60% of microservices projects fail to deliver what they promised. That's insane!

Most devs don't talk about the hidden costs – you end up with separate databases, complicated service discovery, multiple deployment pipelines, inconsistent monitoring... it's a mess unless you really need it.

At my previous company, we spent almost half our time just managing the infrastructure for our "elegant" microservices architecture. We could've built twice as many features with a simpler approach.

That's why I'm betting on Orleans for this WhatsApp CRM. It's how Xbox Live handles millions of concurrent gamers. If it works for them, it'll definitely handle my messaging volume without forcing me to become a Kubernetes expert overnight.

Sometimes the boring solution is the right one. Build a solid, modular system first. You can always break things apart later when you actually have the scaling problems that microservices solve – which, let's be honest, most of us won't have for a long time.

The .NET SDK provides a powerful templating engine that allows developers to create reusable templates for projects, files, and solution structures. This guide covers how to create, package, and distribute custom templates using the dotnet new command-line interface.

Understanding .NET Templates

Templates in .NET are packages that contain source files and a configuration that determines how those files should be transformed when instantiated. They provide a way to standardize project structures, apply consistent patterns, and save time when creating new applications or components.

Key Concepts

• Template: A set of files and folders that can be transformed into a working project or component

• Template Package: A NuGet package containing one or more templates

• Template Engine: The system that processes templates and generates output

Template Structure

A basic template consists of:

1. Source Files and Folders: The content that will be used to generate new projects

2. Configuration Files: JSON files that control how the template behaves

The .template.config Directory

Every template must have a .template.config directory at its root containing at least a template.json file. This file provides metadata and configuration for the template.

template.json

The template.json file defines how the template works. Here's a breakdown of the essential fields:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": ["Category1", "Category2"],
  "identity": "Your.Template.Identity",
  "name": "User-friendly Template Name",
  "shortName": "template-shortname",
  "sourceName": "TemplateSourceName",
  "preferNameDirectory": true,
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

• $schema: Reference to the JSON schema

• author: Creator of the template

• classifications: Categories for organizing templates

• identity: Unique identifier for the template

• name: Display name for the template

• shortName: Command-line alias for the template

• sourceName: The name in source files to be replaced with the user's specified name

• preferNameDirectory: Whether to create a directory for the output

• tags: Metadata for filtering templates

Advanced Template Configuration

Parameters and Symbols

Templates can define parameters that users can specify when creating a new instance:

"symbols": {
  "ParameterName": {
    "type": "parameter",
    "datatype": "bool",
    "defaultValue": "false",
    "description": "Parameter description"
  }
}

Conditional Content

You can include or exclude files based on parameter values:

"sources": [
  {
    "modifiers": [
      {
        "condition": "(!ParameterName)",
        "exclude": ["ExcludedFolder/**/*"]
      }
    ]
  }
]

Post-Creation Actions

You can define actions to be executed after the template is instantiated:

"postActions": [
  {
    "description": "Additional setup steps",
    "manualInstructions": [
      {
        "text": "Instructions for the user after template creation"
      }
    ],
    "actionId": "CB9A6CF3-4F5C-4860-B9D2-03A574959774",
    "continueOnError": true
  }
]

Packaging and Distribution

Creating a NuGet Package

To distribute your template, you need to create a NuGet package:

1. Create a .csproj file to define the package:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0.0</PackageVersion>
    <PackageId>Your.Template.Package</PackageId>
    <Title>Your Template Package</Title>
    <Authors>Your Name</Authors>
    <Description>Your template description</Description>
    <PackageTags>dotnet-new;templates;yourKeywords</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="content/**/*" Exclude="content/**/bin/**;content/**/obj/**" />
    <Compile Remove="**/*" />
  </ItemGroup>
</Project>

2. Organize your files:

YourTemplatePackage/
├── YourTemplatePackage.csproj
└── content/
    ├── .template.config/
    │   └── template.json
    └── YourTemplateFiles/

3. Build the package:

dotnet pack -c Release

Installing Templates

Templates can be installed from various sources:

1. From a NuGet package:

dotnet new install Your.Template.Package

2. From a local .nupkg file:

dotnet new install path/to/Your.Template.Package.1.0.0.nupkg

3. From a file system directory:

dotnet new install path/to/template/directory

Using Templates

Once installed, you can use your template with:

dotnet new template-shortname -n ProjectName [--parameter1 value1]

Template Localization

Templates can be localized to display in different languages. Create a localize folder in the .template.config directory with JSON files named according to the language code:

.template.config/
├── template.json
└── localize/
    ├── templatestrings.en-US.json
    └── templatestrings.es-ES.json

Each localization file contains key-value pairs matching the fields in template.json that should be translated.

Visual Studio Integration

To make your template appear in Visual Studio's "New Project" dialog:

1. Add Visual Studio metadata to the template.json:

"tags": {
  "language": "C#",
  "type": "project",
  "vs-workload": "dotnetcore"
}

2. For complete integration, consider creating a Visual Studio Extension (VSIX) package.

Best Practices

1. Clear naming: Choose descriptive, specific names for your templates

2. Good documentation: Include clear descriptions and examples

3. Minimal dependencies: Avoid unnecessary dependencies

4. Thoughtful defaults: Provide sensible default values for parameters

5. Testing: Test your templates in various environments before distribution

6. Versioning: Follow semantic versioning for your template packages

7. Organization: Keep templates focused and organized by functionality

Troubleshooting

Common Issues

1. Template Not Found: Ensure the template is installed correctly

2. File Not Included: Check your include/exclude patterns

3. Parameter Not Working: Verify parameter configuration in template.json

4. Template Not Visible in VS: Check Visual Studio integration settings

Debugging

For detailed logs when using templates:

dotnet new template-shortname -n ProjectName --verbosity diagnostic

Conclusion

Custom .NET templates are a powerful way to standardize code structures, enforce architectural patterns, and improve productivity. By following this guide, you can create, package, and distribute templates that will help your team or the wider .NET community build better software more efficiently.

Resources

• Official Microsoft Documentation

• Template Schema Reference

• dotnet/templating GitHub Repository