Coder Legion - Recent posts tagged oop

From Anemic Models to Rich Domain Models, DDD Base Entities, and C# Records

Tue, 27 Oct 2026 10:51:17 +0000

When building enterprise applications in C#, a common architectural trap is writing procedural code disguised as object-oriented code. This usually happens when we rely entirely on anemic data bags (public get; set; DTOs) for business logic, forcing our application services to manage all validation and state changes manually.

In this guide, we will tie together Object-Oriented Programming (OOP), the Single Responsibility Principle (SRP), Domain-Driven Design (DDD) Entity base classes, C# Records for Value Objects, Combining Interfaces & Abstract Classes, EF Core Persistence, and Unit Testing into a complete, publication-ready reference.

Part 1: The Anti-Pattern (Anemic Models & DTO Misuse)

An anemic model treats classes as passive data structures with zero behavior. When every model exposes public setters, any part of the codebase can mutate state arbitrarily, bypassing business rules.

The Problematic Approach

// 1. The Anemic Entity (Just a data bag)
public class OrderDto
{
    public Guid Id { get; set; }
    public string CustomerEmail { get; set; }
    public decimal TotalAmount { get; set; }
    public string Status { get; set; } // Can be set to anything from anywhere!
}

// 2. The God Service handling all procedural logic
public class OrderService
{
    public void ProcessOrder(OrderDto order)
    {
        // Business logic scattered in services instead of living in the model
        if (order.TotalAmount <= 0) throw new Exception("Invalid amount");
        order.Status = "Processed"; // Direct mutation without invariant checks
    }
}

Why Anemic Models Fail

Repeated Validation Checks: Since anemic models can't check their own rules, every service or controller writes the same validation code over and over. If a developer forgets one check, a business rule breaks silently.
Unprotected Data (Broken States): Public setters mean code can accidentally create broken data—like a negative order total or an incomplete order marked as completed—which then gets saved to the database.
Hard-to-Fix Rules ("Shotgun Surgery"): When business rules change, you have to hunt through 10 different files and controllers to update identical if statements.

Part 2: DDD Foundation — Entity Base Class & C# Records

In Domain-Driven Design, Entities are defined by their unique identity rather than their attributes, while Value Objects (idiomatically implemented using C# records) are defined entirely by their structural values and are strictly immutable.

1. DDD Entity Base Class

Notice how EqualityComparer<TId> is used below to robustly handle generic identifier comparisons across different types (Guid, int, string, etc.) while ensuring unpersisted entities do not falsely equal each other:

public abstract class Entity<TId>
{
    public TId Id { get; protected set; }

    public override bool Equals(object? obj)
    {
        if (obj is not Entity<TId> other) return false;
        if (ReferenceEquals(this, other)) return true;
        if (GetType() != other.GetType()) return false;

    if (EqualityComparer<TId>.Default.Equals(Id, default!) || 
        EqualityComparer<TId>.Default.Equals(other.Id, default!))
        return false;


        return EqualityComparer<TId>.Default.Equals(Id, other.Id);
    }

public override int GetHashCode() => (GetType().ToString() + Id).GetHashCode();

public static bool operator ==(Entity<TId>? a, Entity<TId>? b) => a?.Equals(b) ?? b is null;
public static bool operator !=(Entity<TId>? a, Entity<TId>? b) => !(a == b);

2. C# Records for Value Objects

Using record gives us value-based structural equality out-of-the-box and immutability by default (init setters).

public record EmailAddress
{
    public string Value { get; init; }

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains("@"))
            throw new ArgumentException("Invalid email format.");
        Value = value;
    }
}

Part 3: Combining Interfaces, Abstract Classes, and DDD Entities

Now we structure our customer hierarchy by inheriting from our DDD Entity<Guid>, implementing our ICustomer interface, and using our EmailAddress value object.

// 1. The Interface defines the full contract
public interface ICustomer
{
    Guid Id { get; }
    EmailAddress Email { get; }
    decimal TotalSpent { get; }
    
    decimal CalculateDiscount(decimal orderAmount);
    void RecordPurchase(decimal amount);
}

// 2. The Abstract Base Class inherits from DDD Entity and implements ICustomer
public abstract class CustomerBase : Entity<Guid>, ICustomer
{
    public EmailAddress Email { get; private set; }
    public decimal TotalSpent { get; private set; }

    protected CustomerBase(Guid id, EmailAddress email)
    {
        Id = id;
        Email = email ?? throw new ArgumentNullException(nameof(email));
        TotalSpent = 0m;
    }

    public void RecordPurchase(decimal amount)
    {
        if (amount <= 0) throw new ArgumentException("Purchase amount must be positive.");
        TotalSpent += amount;
    }

    public abstract decimal CalculateDiscount(decimal orderAmount);
}

// 3. Concrete Implementations
public class RegularCustomer : CustomerBase
{
    public RegularCustomer(Guid id, EmailAddress email) : base(id, email) { }

    public override decimal CalculateDiscount(decimal orderAmount) => 0m;
}

public class VipCustomer : CustomerBase
{
    public decimal CreditLimit { get; private set; }

    public VipCustomer(Guid id, EmailAddress email, decimal creditLimit) : base(id, email)
    {
        if (creditLimit < 0) throw new ArgumentException("Credit limit cannot be negative.");
        CreditLimit = creditLimit;
    }

    public override decimal CalculateDiscount(decimal orderAmount) => orderAmount * 0.10m;
}

Part 4: The Rich Domain Model (`Order`)

Our Order inherits from Entity<Guid>, enforces business invariants, and coordinates with ICustomer.

public class Order : Entity<Guid>
{
    public ICustomer Customer { get; }
    public decimal TotalAmount { get; private set; }
    public OrderStatus Status { get; private set; }

    public Order(Guid id, ICustomer customer, decimal initialAmount)
    {
        Id = id;
        Customer = customer ?? throw new ArgumentNullException(nameof(customer));
        
        if (initialAmount <= 0)
            throw new ArgumentException("Order amount must be greater than zero.");

        TotalAmount = initialAmount;
        Status = OrderStatus.Draft;

        ApplyCustomerDiscount();
    }

    private void ApplyCustomerDiscount()
    {
        decimal discount = Customer.CalculateDiscount(TotalAmount);
        TotalAmount -= discount;
    }

    public void AddItem(decimal itemPrice)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Cannot modify an order after it has been submitted.");

        TotalAmount += itemPrice;
    }

    public void SubmitPayment()
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Order is already processed.");

        Status = OrderStatus.Submitted;
    }
}

public enum OrderStatus { Draft, Submitted, Completed }

Part 5: Orchestrating with SRP and Dependency Injection

Our application service (OrderProcessor) focuses purely on coordination (following the Single Responsibility Principle).

public class OrderProcessor
{
    private readonly IOrderRepository _repository;
    private readonly IPaymentGateway _paymentGateway;
    private readonly IEmailNotifier _notifier;
    private readonly ILogger<OrderProcessor> _logger;

    public OrderProcessor(
        IOrderRepository repository,
        IPaymentGateway paymentGateway,
        IEmailNotifier notifier,
        ILogger<OrderProcessor> logger)
    {
        _repository = repository;
        _paymentGateway = paymentGateway;
        _notifier = notifier;
        _logger = logger;
    }

    public async Task ProcessAsync(Guid orderId)
    {
        var order = await _repository.GetByIdAsync(orderId);
        if (order == null) throw new KeyNotFoundException("Order not found.");

        order.SubmitPayment();

        if (!await _paymentGateway.ChargeAsync(order.TotalAmount))
        {
            throw new InvalidOperationException("Payment failed.");
        }

        order.Customer.RecordPurchase(order.TotalAmount);

        await _repository.SaveAsync(order);
        await _notifier.SendConfirmationAsync(order.Customer.Email.Value);

        _logger.LogInformation("Successfully processed order {OrderId}", order.Id);
    }
}

Part 6: Persistence with EF Core (Mapping Records & TPH)

Using EF Core Entity configurations to map our DDD entities, value objects (records via owned types), and inheritance hierarchy.

public class AppDbContext : DbContext
{
    public DbSet<CustomerBase> Customers => Set<CustomerBase>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Configure Customer Inheritance (TPH)

modelBuilder.Entity()

        .HasKey(c => c.Id);

    modelBuilder.Entity<CustomerBase>()
        .OwnsOne(c => c.Email, email =>
        {
            email.Property(e => e.Value).HasColumnName("Email").IsRequired();
        });

    modelBuilder.Entity<CustomerBase>()
        .HasDiscriminator<string>("CustomerType")
        .HasValue<RegularCustomer>("Regular")
        .HasValue<VipCustomer>("VIP");

    // Configure Order Entity
    modelBuilder.Entity<Order>()
        .HasKey(o => o.Id);

    modelBuilder.Entity<Order>()
        .HasOne(o => o.Customer)
        .WithMany()
        .HasForeignKey("CustomerId");

}
}

Part 7: Unit Testing with Records & Entities

public class DomainTests
{
    [Fact]
    public void VipCustomer_WithValidData_CalculatesDiscountAndTracksSpend()
    {
        var email = new EmailAddress("*Emails are not allowed*");
        ICustomer customer = new VipCustomer(Guid.NewGuid(), email, 5000.00m);
        var order = new Order(Guid.NewGuid(), customer, 200.00m);

        // 200 - 10% = 180
        Assert.Equal(180.00m, order.TotalAmount);

        customer.RecordPurchase(order.TotalAmount);
        Assert.Equal(180.00m, customer.TotalSpent);
    }
}

References & Further Reading

Martin Fowler (2003): AnemicDomainModel — Read article.
Eric Evans (2003): Domain-Driven Design: Tackling Complexity in the Heart of Software — Addison-Wesley Professional.
Robert C. Martin (2017): Clean Architecture: A Craftsman's Guide to Software Structure and Design — Prentice Hall.

The Art of Object-Oriented Programming

Thu, 17 Sep 2026 18:31:07 +0000

Most developers learn OOP backwards — memorize four buzzwords, pass the exam, then go write procedural code inside classes. That’s not object-oriented programming. That’s just spaghetti with labels on it.

OOP is a design philosophy before it’s a syntax. It’s a way of breaking a complex system into smaller, self-contained pieces — pieces that each know their job, protect their own state, and can talk to each other without the whole thing falling apart. The syntax is easy. The thinking is what takes years.

Classes & Objects

A class is a blueprint. An object is the thing built from it.

Think of an architect’s floor plan for a house. The blueprint describes two bedrooms, a kitchen, a front door. But you can’t live in the blueprint. When a builder follows it and constructs an actual house — that’s the object. Build fifty houses from the same blueprint and each one is its own thing: different paint, different furniture, different family inside.

Same class. Two separate objects. This is the starting point.

State, Behavior & Identity

Every object carries three things: what it knows, what it can do, and what makes it uniquely itself.

State is the data — a bank account’s balance, a user’s email address. Behavior is the methods — a bank account can deposit, withdraw, generate a statement. Identity is what separates one object from another even if their data is identical. Two bank accounts with the same zero balance are still two separate accounts.

A constructor is where this all begins. It’s the object’s moment of birth — where you set up valid, usable initial state before anyone else touches it.

Good constructors do one thing: produce a valid object and get out. No database calls, no network requests, no side effects. Just state.

Methods are where responsibility lives — but the most important question about any method isn’t “does it work?” It’s “does it belong here?” A User class should not have a method called sendInvoice(). That's not the user's job. When a method doesn't belong, it's a signal that your boundaries are wrong.

The Four Pillars — What They Actually Mean

Encapsulation

Encapsulation is not “make things private.” That’s the mechanism. The principle is protecting your state from being changed in ways you didn’t intend.

Think of a vending machine. You can see the snacks through the glass, put money in, and press a button. But you cannot reach inside and grab whatever you want. The machine controls its own internals. You interact through a defined interface.

The stock field is private. No external code can set stock = 999. All changes go through purchase(), which enforces the rules. That's the point — not hiding data for its own sake, but controlling how it changes.

Abstraction

Abstraction hides complexity behind a simple interface.

When you drive a car, you don’t need to understand internal combustion to press the accelerator. The car abstracts all of that away. You get a pedal. You press it. The machinery underneath is none of your business.

The calling code just calls .charge(). It doesn't care how. Tomorrow you add a PayPal gateway. The calling code doesn't change. That's abstraction doing its job.

Inheritance

Inheritance captures the “is-a” relationship. A Dog is an Animal. A SavingsAccount is a BankAccount. You inherit the shared structure, then specialize.

Here’s where most people go wrong: they use inheritance for code reuse rather than for actual “is-a” relationships. If you’re inheriting from a class just to borrow two methods, you’ve built a dependency that’ll betray you when the parent class needs to change. Inheritance should model a genuine relationship — not be a shortcut.

Polymorphism

Polymorphism means the same interface, different behavior. One method name, many implementations depending on which object you’re actually calling it on.

printArea doesn't know or care whether it's working with a circle or a rectangle. It calls .area() and trusts the object to do the right thing. Add a Triangle tomorrow — printArea doesn't need to touch it. This is what makes systems extensible without becoming fragile.

Composition vs. Inheritance — The Choice Nobody Teaches Properly

Real OOP design lives in this question: should this object be the other thing, or should it have it?

A Car doesn't inherit from Engine. That would be absurd. A Car has an engine. It uses an engine. That's composition.

If tomorrow you need an ElectricEngine, you swap it in. The Car class doesn't change at all. Inheritance would have made that painful. Composition keeps it trivial.

The general rule: prefer composition. Use inheritance only when you have a genuine “is-a” relationship and you want to express that relationship explicitly in the design.

Association, Aggregation & Composition

These three describe how tightly objects are bound to each other — and it matters more than most tutorials acknowledge.

Association is the loosest connection. A Doctor treats Patients. They know about each other. Neither owns the other. They can both exist independently.

Aggregation is a whole-part relationship where the parts survive without the whole. A Team has Players. Dissolve the team, the players still exist somewhere.

Composition is the tightest bond — the part cannot exist without the whole. A House has Rooms. Destroy the house, the rooms aren't standalone things anymore.

Getting this right isn’t academic. It determines how you structure your database schemas, how you handle object lifecycles, and what breaks when something gets deleted.

Coupling & Cohesion — The Two Dials

Every system has two dials you’re constantly tuning.

Coupling measures how much one class depends on another. High coupling means a change in one class ripples into others, sometimes into five others you didn’t expect. Low coupling means classes can change independently. You want low coupling.

Cohesion measures how focused a class is on a single purpose. A class that handles user registration, sends confirmation emails, generates PDFs, and logs activity — that’s low cohesion. It’s doing four different jobs. When you split that into four focused classes, each becomes easier to test, easier to change, and easier to understand.

High cohesion and low coupling together produce modular code. A UserRegistrationService that only handles registration and receives its email sender and logger through injection rather than creating them — that's what well-designed OOP looks like in practice.

The question to ask every time you write a class: if I had to change this one thing, how many other places would break?

Common OOP Design Mistakes

A few patterns that feel right until they don’t:

The God Object. One massive class that knows everything and controls everything. Usually named Manager, Handler, or Utilities. This class grows without limit because "it's already there." Split it ruthlessly.

Anemic domain models. Objects that are just bags of data — nothing but getters and setters — with all the actual logic sitting in a separate service. This is procedural code wearing OOP clothes. Behavior belongs with the data it operates on.

Deep inheritance chains. Five levels deep, the sixth developer can’t understand what they’re actually working with. The deeper the chain, the harder it breaks. Flatten it with composition.

Abstracting too early. Building interfaces and abstract base classes before you have two real concrete variations. Write the concrete thing first. Abstract only when you see the pattern emerge from actual code — not from prediction.

A Small Real-World Example

Consider an order system. A bad design puts everything into Order: it calculates totals, applies discounts, sends emails, and updates inventory. Every time any one of those things changes, you're editing this one class.

A better design:

Three classes. Three clear jobs. Order knows its own data. DiscountService knows how pricing works. OrderNotifier knows how to reach the customer. None of them know too much about the others. Swap email notifications for SMS tomorrow — Order doesn't care, DiscountService doesn't care. Only OrderNotifier changes.

This is low coupling and high cohesion working together. It’s not clever. It’s disciplined.

Conclusion: OOP as a Design Mindset

OOP isn’t about memorizing four words. It’s not a style guide. It’s a discipline for managing complexity — for breaking a system that’s too big to hold in your head into pieces that each have a clear owner and a clear job.

The programmers who use it well think before they type. They ask: where does this knowledge live? Who is responsible for this behavior? What happens to the rest of the system if this changes? They treat their objects the way an architect treats walls — with respect for what they hold up.

Learn the concepts once. Then spend the rest of your time learning how they work together. The syntax is a day’s work. The design sense takes years. That’s where the actual art is.

References

Gamma, Helm, Johnson, Vlissides — Design Patterns: Elements of Reusable Object-Oriented Software
Martin Fowler — Refactoring: Improving the Design of Existing Code
Robert C. Martin — Clean Code: A Handbook of Agile Software Craftsmanship
MDN Web Docs — Object-Oriented Programming in JavaScript
Mattias Petter Johansson — Composition over Inheritance (FunFunFunction, YouTube)

Find me across the web:

Portfolio: ahmershah.dev
Crunchbase: @syed-ahmer-shah
Crunchbase Company: @syedahmershah
Clutch: @syed-ahmer-shah
Tech Behemoth: @syed-ahmer-shah
Design Rush: @syed-ahmer-shah
Edverise: @syed-ahmer-shah
Trust Pilot: @ahmershah.dev
LinkedIn: Syed Ahmer Shah
GitHub: @ahmershahdev
AWS Builder Profile: @syedahmershah
DEV: @syedahmershah
Medium: @syedahmershah
Hashnode: @syedahmershah
Substack: @syedahmershah
HackerNoon: @syedahmershah
Substack: @syedahmershah
Facebook: @ahmershahdev
Linkedin Page: @syedahmershah
YouTube: @ahmershahdev
Instagram: @ahmershahdev
TikTok: @ahmershahdev

The Object-Oriented Design Handbook: SOLID, GRASP, and the Principles That Make Software Scale

Tue, 21 Jul 2026 20:48:29 +0000

Imagine walking into a very busy factory that produces a highly in-demand product. This factory is packed with workers from different parts of the project, coming together to get it delivered. And because it's a very large factory, there can be up to 100 workers at the same time, channeling their energies into different tasks.

But the amazing thing is, these workers aren't running into each other, mixing tasks up, and causing confusion and conflicts. Instead, everyone has a clear role, pattern, methodology, skillset, and defined responsibilities, as well as a structured way of interacting with each other.

No one person does everything, and everyone does their own thing (the right thing). Because of this, the system works productively, is scalable, and delivers the product in a clearly defined and structured manner.

This is what building software looks like when it is properly designed, following strategically laid-down rules and principles.

Object-Oriented Design is the engineering equivalent of running this factory with the discipline of breaking complexities into clear, well-defined objects where each of them have defined purposes, boundaries, and rules for interaction.

This is more about designing a system that does not collapse as it grows.

OOP techniques create a huge difference between an app that becomes impossible to maintain after some time and an app that scales gracefully as features, users, and complexities increase.

Many developers would think of Object-Oriented Design as classes, objects, constructors, and maybe inheritance, but OOP transcends more than just classes. It is about designing relationships.

So technically, Object-Oriented Design is the core discipline of breaking a large or medium application into small and focused objects that each does one thing well.

While following this design, you would think of things like:

What objects should exist?

What modifiers should be used to create this object or class?

What responsibilities should a class have?

How should objects behave and communicate with each other?

How can I prevent an object from being too exposed or doing too much?

All of these questions and many more strategic ones help fine-tune your application towards achieving the productivity and scalability Object-Oriented Design offers.

Having understood this, there are core principles that make a fantastic design possible. These rules keep your objects clean, focused, reusable, scalable, and interactive following the actual use cases they are meant to fulfill.

This handbook breaks the principles into 7 major slices:

SOLID Principles — The foundation of robust object design

GRASP Principles — General Responsibility Assignment patterns

Package Principles — Applying SOLID to modular packages

Class Design Principles — Best practices for designing classes

Design Pattern Principles — Reusable solutions to common design problems

Error Handling Principles — Structuring failures without breaking the system

Testing Principles — Ensuring your objects behave as expected

The aim is to understand all the principles that make the difference between a system that collapses under complexity and one that scales gracefully as features, users, and requirements grow.

Table of Contents

SOLID Principles: The Foundation of Robust Object Design

GRASP Principles: General Responsibility Assignment Patterns

Package Principles: Applying SOLID to Modular Packages

Class Design Principles: Best Practices for Designing Classes

Design Pattern Principles: Reusable Solutions to Common Problems

Error Handling Principles: Structuring Failures Without Breaking the System

Testing Principles: Ensuring Your Objects Behave as Expected

Conclusion

SOLID Principles: The Foundation of Robust Object Design

SOLID is an acronym coined by Robert C. Martin (Uncle Bob) representing five fundamental principles that form the bedrock of object-oriented design. Think of SOLID as the factory's core operating rules: the non-negotiables that keep everything running smoothly.

These five principles work together to ensure your code is:

Maintainable: Easy to modify without breaking existing functionality

Scalable: Handles growth in features and complexity

Testable: Each component can be tested in isolation

Flexible: Adapts to changing requirements without major rewrites

Single Responsibility Principle (SRP)

Definition: A class should have one, and only one, reason to change.

Factory Analogy: Imagine a factory worker who assembles engines, packages products, does quality checks, AND manages inventory. When any of these processes change, this one worker must adapt. This creates confusion, errors, and bottlenecks.

Instead, assign ONE clear job per worker:

Worker A: Assembles engines

Worker B: Packages products

Worker C: Quality inspection

Worker D: Inventory management

Now when packaging requirements change, only Worker B adapts. The system stays stable.

Code Example - Violating SRP:

// ❌ BAD: This class has multiple responsibilities
class UserManager {
// Responsibility 1: User validation
bool validateEmail(String email) {

return email.contains('@');

}

// Responsibility 2: Database operations
Future saveUser(User user) async {

await database.insert('users', user.toJson());

}

// Responsibility 3: Email notifications
Future sendWelcomeEmail(User user) async {

await emailService.send(user.email, 'Welcome!');

}

// Responsibility 4: Logging
void logUserCreation(User user) {

logger.log('User created: ${user.name}');

}
}

// Problem: If email validation rules change, OR database schema changes,
// OR email template changes, OR logging format changes — you modify the SAME class.
// This violates SRP.

Code Example - Following SRP:

// ✅ GOOD: Each class has ONE responsibility

class UserValidator {
bool validateEmail(String email) {

return email.contains('@') && email.length > 5;

}

bool validatePassword(String password) {

return password.length >= 8;

}
}

class UserRepository {
Future saveUser(User user) async {

await database.insert('users', user.toJson());

}

Future<User?> findUserById(String id) async {

final data = await database.query('users', where: 'id = ?', args: [id]);
return data != null ? User.fromJson(data) : null;

}
}

class UserNotificationService {
Future sendWelcomeEmail(User user) async {

await emailService.send(user.email, 'Welcome to our platform!');

}
}

class UserLogger {
void logUserCreation(User user) {

logger.info('User created: ${user.name} at ${DateTime.now()}');

}
}

// Orchestrate these focused classes in a UseCase
class CreateUserUseCase {
final UserValidator validator;
final UserRepository repository;
final UserNotificationService notificationService;
final UserLogger logger;

CreateUserUseCase({

required this.validator,
required this.repository,
required this.notificationService,
required this.logger,

});

Future execute(User user) async {

if (!validator.validateEmail(user.email)) {
  throw ValidationException('Invalid email');
}
await repository.saveUser(user);
await notificationService.sendWelcomeEmail(user);
logger.logUserCreation(user);

}
}

Benefits:

Each class has ONE reason to change

Easy to test in isolation

Easy to reuse (UserValidator can be used elsewhere)

Clear boundaries and responsibilities

When to Apply:

When a class is doing more than one thing

When changes in one area force changes in unrelated areas

When testing requires mocking multiple unrelated dependencies

Open/Closed Principle (OCP)

Definition: Software entities should be open for extension, but closed for modification.

Factory Analogy: Your factory produces cars. Now management wants to add truck production.

Bad approach: Modify the existing car assembly line (risky, might break car production). Good approach: Add a new truck assembly line (extends capability without touching the car line).

Code Example - Violating OCP:

// ❌ BAD: Must modify class to add new payment methods
class PaymentProcessor {
void processPayment(String paymentType, double amount) {

if (paymentType == 'credit_card') {
  print('Processing credit card payment: \$${amount}');
} else if (paymentType == 'paypal') {
  print('Processing PayPal payment: \$${amount}');
} else if (paymentType == 'crypto') {
  print('Processing crypto payment: \$${amount}');
}
// Adding Apple Pay? Must modify this class and add another if-else.

}
}

Code Example - Following OCP:

// ✅ GOOD: Open for extension, closed for modification

abstract class PaymentMethod {
Future process(double amount);
String get name;
}

class CreditCardPayment extends PaymentMethod {
@override
String get name => 'Credit Card';

@override
Future process(double amount) async {

print('Processing credit card: \$${amount}');

}
}

class PayPalPayment extends PaymentMethod {
@override
String get name => 'PayPal';

@override
Future process(double amount) async {

print('Processing PayPal: \$${amount}');

}
}

// New payment method added WITHOUT modifying PaymentProcessor
class ApplePayPayment extends PaymentMethod {
@override
String get name => 'Apple Pay';

@override
Future process(double amount) async {

print('Processing Apple Pay: \$${amount}');

}
}

class PaymentProcessor {
Future processPayment(PaymentMethod paymentMethod, double amount) async {

print('Processing ${paymentMethod.name} payment...');
await paymentMethod.process(amount);
print('Payment completed!');

}
}

Benefits:

Add new features without touching existing code

Reduces risk of breaking working functionality

Easier testing (new payment methods tested independently)

Scalable architecture

When to Apply:

When you anticipate new variations of behavior

When you have if-else or switch statements based on types

When adding features requires modifying existing classes

Liskov Substitution Principle (LSP)

Definition: Objects of a subclass should be replaceable with objects of the parent class without breaking the application.

In simpler terms: if class B extends class A, anywhere you use A, you should be able to use B and the program should still work correctly.

Factory Analogy: Your factory has a standard packaging machine. You introduce a new upgraded packaging machine that does everything the old one does, plus more. Any production line that used the old machine can switch to the new one without any changes to the line itself. If the new machine broke the production line, it would violate LSP.

Code Example - Violating LSP:

// ❌ BAD: Subclass breaks the expected behavior of the parent

class Bird {
void fly() {

print('Flying...');

}
}

class Penguin extends Bird {
@override
void fly() {

// Penguins cannot fly — this throws an exception!
throw UnsupportedError('Penguins cannot fly');

}
}

void makeBirdFly(Bird bird) {
bird.fly(); // This will crash when bird is a Penguin
}

// Usage
makeBirdFly(Bird()); // Works fine
makeBirdFly(Penguin()); // Runtime crash — LSP violated

The problem is clear. Penguin cannot honor the fly() contract that Bird promises. Substituting Penguin for Bird breaks the program.

Code Example - Following LSP:

// ✅ GOOD: Proper hierarchy that respects behavioral contracts

abstract class Bird {
void eat();
void sleep();
String get name;
}

abstract class FlyingBird extends Bird {
void fly();
}

abstract class SwimmingBird extends Bird {
void swim();
}

class Eagle extends FlyingBird {
@override
String get name => 'Eagle';

@override
void fly() => print('Eagle soaring high');

@override
void eat() => print('Eagle eating fish');

@override
void sleep() => print('Eagle sleeping in nest');
}

class Penguin extends SwimmingBird {
@override
String get name => 'Penguin';

@override
void swim() => print('Penguin swimming gracefully');

@override
void eat() => print('Penguin eating krill');

@override
void sleep() => print('Penguin sleeping on ice');
}

// Each function works with the correct abstraction
void makeBirdFly(FlyingBird bird) => bird.fly();
void makeBirdSwim(SwimmingBird bird) => bird.swim();

// Usage
makeBirdFly(Eagle()); // Works perfectly
makeBirdSwim(Penguin()); // Works perfectly

A Real-World Example in Dart:

// ❌ BAD: ReadOnlyRepository violates the Repository contract
abstract class Repository {
Future<T?> findById(String id);
Future save(T entity);
Future delete(String id);
}

class ReadOnlyUserRepository extends Repository {
@override
Future<User?> findById(String id) async {

return await database.find(id);

}

@override
Future save(User entity) async {

throw UnsupportedError('This repository is read-only'); // LSP violation

}

@override
Future delete(String id) async {

throw UnsupportedError('This repository is read-only'); // LSP violation

}
}

// ✅ GOOD: Separate abstractions for separate capabilities
abstract class ReadableRepository {
Future<T?> findById(String id);
Future<List> findAll();
}

abstract class WritableRepository extends ReadableRepository {
Future save(T entity);
Future delete(String id);
}

class UserRepository extends WritableRepository {
@override
Future<User?> findById(String id) async => await database.find(id);

@override
Future<List> findAll() async => await database.findAll();

@override
Future save(User entity) async => await database.insert(entity);

@override
Future delete(String id) async => await database.delete(id);
}

class AuditLogRepository extends ReadableRepository {
@override
Future<AuditLog?> findById(String id) async => await database.find(id);

@override
Future<List> findAll() async => await database.findAll();
// No save or delete — audit logs are immutable by design
}

Benefits:

Predictable behavior when using polymorphism

Safer use of inheritance

Code that uses base types continues to work correctly with any subtype

Fewer runtime surprises

When to Apply:

Before creating any subclass — ask: "Can this subclass honor every contract the parent promises?"

When a subclass needs to throw UnsupportedError for inherited methods

When overriding a method in a way that weakens the expected behavior

Interface Segregation Principle (ISP)

Definition: A class should not be forced to implement interfaces it does not use. Clients should depend only on the methods they actually need.

In other words, prefer many small, focused interfaces over one large, general-purpose interface.

Factory Analogy: Imagine a job description that requires every worker to assemble products, operate heavy machinery, drive a forklift, manage accounts, AND handle customer service. A worker hired for packaging should not be required to have a forklift license. Each role should have the specific skills it actually needs.

Code Example - Violating ISP:

// ❌ BAD: One fat interface forces implementations to stub out unused methods
abstract class Worker {
void work();
void eat();
void sleep();
void attendMeeting();
void writeReport();
void operateMachinery();
}

// A robot worker should not be forced to implement eat, sleep, or attendMeeting
class RobotWorker implements Worker {
@override
void work() => print('Robot working 24/7');

@override
void eat() => throw UnsupportedError('Robots do not eat'); // Forced stub

@override
void sleep() => throw UnsupportedError('Robots do not sleep'); // Forced stub

@override
void attendMeeting() => throw UnsupportedError('Robots do not attend meetings');

@override
void writeReport() => throw UnsupportedError('Robots do not write reports');

@override
void operateMachinery() => print('Robot operating machinery');
}

Code Example - Following ISP:

// ✅ GOOD: Small, focused interfaces

abstract class Workable {
void work();
}

abstract class Eatable {
void eat();
}

abstract class Sleepable {
void sleep();
}

abstract class MeetingAttendable {
void attendMeeting();
}

abstract class MachineryOperable {
void operateMachinery();
}

// Human worker implements only what humans do
class HumanWorker implements Workable, Eatable, Sleepable, MeetingAttendable {
@override
void work() => print('Human working with focus');

@override
void eat() => print('Human eating lunch');

@override
void sleep() => print('Human sleeping 8 hours');

@override
void attendMeeting() => print('Human attending standup');
}

// Robot worker implements only what robots do
class RobotWorker implements Workable, MachineryOperable {
@override
void work() => print('Robot working 24/7');

@override
void operateMachinery() => print('Robot operating machinery');
}

A Real-World Flutter Example:

// ❌ BAD: Fat repository interface forces every implementation to support all operations
abstract class UserRepository {
Future<User?> findById(String id);
Future save(User user);
Future delete(String id);
Future exportToCsv();
Future sendBulkEmail(List users);
Future<Map<String, dynamic>> generateReport();
}

// ✅ GOOD: Each interface has a single, focused purpose
abstract class UserReadRepository {
Future<User?> findById(String id);
Future<List> findAll();
}

abstract class UserWriteRepository {
Future save(User user);
Future delete(String id);
}

abstract class UserExportRepository {
Future exportToCsv();
}

abstract class UserCommunicationRepository {
Future sendBulkEmail(List users);
}

// Implementations can mix and match what they support
class SqlUserRepository implements UserReadRepository, UserWriteRepository {
@override
Future<User?> findById(String id) async => await db.find(id);

@override
Future<List> findAll() async => await db.findAll();

@override
Future save(User user) async => await db.insert(user);

@override
Future delete(String id) async => await db.delete(id);
}

Benefits:

No class is forced to implement methods it does not need

Smaller interfaces are easier to implement and test

Changes to one interface do not affect unrelated implementations

More focused and meaningful contracts

When to Apply:

When an interface has methods that some implementations must stub out or throw for

When adding a new method to an interface would force changes in unrelated classes

When an interface is doing too many different things

Dependency Inversion Principle (DIP)

Definition: High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.

In practical terms: depend on interfaces and abstract classes, not on concrete implementations.

Factory Analogy: The factory manager (high-level) should not directly operate a specific brand of machine (low-level). Instead, the manager issues instructions to a machine operator interface. Any brand of machine that fulfills the operator interface can be plugged in. The manager never changes when the machine brand changes.

Code Example - Violating DIP:

// ❌ BAD: High-level class directly depends on a concrete low-level class

class MySqlDatabase {
Future insert(String table, Map<String, dynamic> data) async {

// MySQL-specific implementation
print('Inserting into MySQL: $table');

}

Future<Map<String, dynamic>?> query(String table, String id) async {

// MySQL-specific implementation
print('Querying MySQL: $table with id $id');
return null;

}
}

// UserService directly depends on MySqlDatabase
// If you ever switch to PostgreSQL or Hive, UserService must change
class UserService {
final MySqlDatabase _database = MySqlDatabase(); // concrete dependency

Future createUser(User user) async {

await _database.insert('users', user.toJson());

}
}

Code Example - Following DIP:

// ✅ GOOD: Both high-level and low-level depend on abstraction

// The abstraction
abstract class Database {
Future insert(String table, Map<String, dynamic> data);
Future<Map<String, dynamic>?> query(String table, String id);
Future delete(String table, String id);
}

// Low-level module: concrete implementation
class MySqlDatabase implements Database {
@override
Future insert(String table, Map<String, dynamic> data) async {

print('MySQL: Inserting into $table');

}

@override
Future<Map<String, dynamic>?> query(String table, String id) async {

print('MySQL: Querying $table with id $id');
return null;

}

@override
Future delete(String table, String id) async {

print('MySQL: Deleting from $table with id $id');

}
}

// Another implementation — swap with zero changes to UserService
class HiveDatabase implements Database {
@override
Future insert(String table, Map<String, dynamic> data) async {

print('Hive: Inserting into $table');

}

@override
Future<Map<String, dynamic>?> query(String table, String id) async {

print('Hive: Querying $table with id $id');
return null;

}

@override
Future delete(String table, String id) async {

print('Hive: Deleting from $table with id $id');

}
}

// High-level module: depends on the abstraction, not the concrete class
class UserService {
final Database _database; // abstraction

UserService(this._database); // injected from outside

Future createUser(User user) async {

await _database.insert('users', user.toJson());

}

Future<User?> getUser(String id) async {

final data = await _database.query('users', id);
return data != null ? User.fromJson(data) : null;

}
}

// Usage — swap implementations without touching UserService
final service = UserService(MySqlDatabase());
final serviceWithHive = UserService(HiveDatabase());

// In tests — inject a mock
final testService = UserService(MockDatabase());

Benefits:

High-level business logic is independent of infrastructure details

Swap implementations (databases, APIs, storage) without changing business code

Test high-level modules with mock implementations

Looser coupling between layers of the system

When to Apply:

When a class directly instantiates its dependencies with new or a constructor call

When changing a low-level module forces changes in high-level modules

When you cannot test a class without its real dependencies being present

GRASP Principles: General Responsibility Assignment Patterns

GRASP stands for General Responsibility Assignment Software Patterns. Introduced by Craig Larman in his book "Applying UML and Patterns," GRASP provides nine patterns that guide how to assign responsibilities to classes and objects.

If SOLID tells you the rules of good object design, GRASP tells you the thinking process behind assigning the right job to the right object.

Information Expert

Definition: Assign a responsibility to the class that has the information needed to fulfill it.

The class that knows the most about the data required to perform a task should be the one to perform that task.

// ❌ BAD: Order total calculated outside the Order class
class OrderService {
double calculateTotal(Order order) {

double total = 0;
for (final item in order.items) {
  total += item.price * item.quantity;
}
return total;

}
}

// ✅ GOOD: Order calculates its own total because it has all the information
class Order {
final List items;
final String id;
final String customerId;

Order({required this.items, required this.id, required this.customerId});

// Order is the Information Expert — it has items, so it calculates total
double get total {

return items.fold(0, (sum, item) => sum + (item.price * item.quantity));

}

bool get isEmpty => items.isEmpty;

int get itemCount => items.length;
}

class OrderItem {
final String productId;
final double price;
final int quantity;

OrderItem({

required this.productId,
required this.price,
required this.quantity,

});
}

The Order class is the Information Expert for its total because it owns the items. Putting calculateTotal in a service class means that service must reach into Order's data to do work that Order is better positioned to do itself.

Creator

Definition: Assign class B the responsibility of creating an instance of class A if B contains A, aggregates A, closely uses A, or has the initializing data for A.

// ✅ GOOD: Order creates OrderItems because Order aggregates them
class Order {
final List _items = [];
final String id;
final String customerId;

Order({required this.id, required this.customerId});

// Order is the Creator of OrderItems — it aggregates them
void addItem(String productId, double price, int quantity) {

_items.add(OrderItem(
  productId: productId,
  price: price,
  quantity: quantity,
));

}

List get items => List.unmodifiable(_items);
}

// ✅ GOOD: OrderFactory creates Orders because it has all the initialization data
class OrderFactory {
final String _customerId;

OrderFactory(this._customerId);

Order createOrder() {

return Order(
  id: DateTime.now().millisecondsSinceEpoch.toString(),
  customerId: _customerId,
);

}
}

Controller

Definition: Assign the responsibility of handling system events to a class that represents the overall system, a use case scenario, or a session.

The Controller is not a UI widget. It is the first object beyond the UI layer that handles a system operation. In Flutter with Clean Architecture, this maps directly to your use case or notifier layer.

// ❌ BAD: UI widget handling business logic directly
class CheckoutWidget extends StatelessWidget {
Future _onCheckout() async {

// Widget is directly handling domain logic
final cart = CartRepository().getCart();
if (cart.isEmpty) return;

final order = Order(id: 'ord_1', customerId: 'usr_1');
await PaymentService().process(order);
await InventoryService().updateStock(order);
await NotificationService().sendConfirmation(order);

}
}

// ✅ GOOD: Controller (use case) handles the system operation
class CheckoutUseCase {
final CartRepository _cartRepository;
final PaymentService _paymentService;
final InventoryService _inventoryService;
final NotificationService _notificationService;

CheckoutUseCase({

required CartRepository cartRepository,
required PaymentService paymentService,
required InventoryService inventoryService,
required NotificationService notificationService,

}) : _cartRepository = cartRepository,

    _paymentService = paymentService,
    _inventoryService = inventoryService,
    _notificationService = notificationService;

Future<Result<Order, AppException>> execute(String customerId) async {

final cart = await _cartRepository.getCart(customerId);
if (cart.isEmpty) return Result.failure(AppException.emptyCart());

final order = Order.fromCart(cart, customerId);
await _paymentService.process(order);
await _inventoryService.updateStock(order);
await _notificationService.sendConfirmation(order);

return Result.success(order);

}
}

// Widget delegates to the controller
class CheckoutWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {

return ElevatedButton(
  onPressed: () => ref.read(checkoutNotifierProvider.notifier).checkout(),
  child: const Text('Checkout'),
);

}
}

Low Coupling

Definition: Assign responsibilities so that coupling (dependency between classes) remains low. A class with low coupling is easier to change, test, and reuse.

Coupling is the degree to which one class knows about or depends on another. High coupling means changing one class forces changes in many others. Low coupling means each class is as independent as possible.

// ❌ BAD: High coupling — UserService knows about specific implementations
class UserService {
final MySqlDatabase _database = MySqlDatabase();
final SmtpEmailService _emailService = SmtpEmailService();
final FirebaseAnalytics _analytics = FirebaseAnalytics();

Future registerUser(User user) async {

await _database.insert('users', user.toJson());
await _emailService.sendWelcome(user.email);
_analytics.logEvent('user_registered');

}
}

// ✅ GOOD: Low coupling — UserService depends on abstractions
class UserService {
final UserRepository _repository;
final EmailService _emailService;
final AnalyticsService _analytics;

UserService({

required UserRepository repository,
required EmailService emailService,
required AnalyticsService analytics,

}) : _repository = repository,

    _emailService = emailService,
    _analytics = analytics;

Future registerUser(User user) async {

await _repository.save(user);
await _emailService.sendWelcome(user.email);
_analytics.logEvent('user_registered');

}
}

Low coupling directly enables testability. When UserService depends on abstractions, you inject mocks in tests and verify behavior without touching a real database, a real email server, or a real analytics service.

High Cohesion

Definition: Assign responsibilities so that cohesion (how closely related a class's responsibilities are) remains high. A class with high cohesion has a clear, focused purpose and all its methods contribute to that purpose.

Low cohesion is the sign of a class that is doing too many unrelated things. High cohesion is the sign of a class that knows exactly what it is and does it well.

// ❌ BAD: Low cohesion — UserManager does unrelated things
class UserManager {
Future saveUser(User user) async { / ... / }
Future sendEmail(String email, String body) async { / ... / }
void generatePdfReport(List users) { / ... / }
Future syncWithExternalApi(User user) async { / ... / }
void logActivity(String message) { / ... / }
}

// ✅ GOOD: High cohesion — each class has a clear, focused purpose
class UserRepository {
Future save(User user) async { / ... / }
Future<User?> findById(String id) async { / ... / }
Future<List> findAll() async { / ... / }
Future delete(String id) async { / ... / }
}

class UserEmailService {
Future sendWelcome(String email) async { / ... / }
Future sendPasswordReset(String email) async { / ... / }
Future sendAccountSuspended(String email) async { / ... / }
}

class UserReportService {
void generatePdfReport(List users) { / ... / }
void generateCsvExport(List users) { / ... / }
}

High cohesion and low coupling are two sides of the same coin. A class with high cohesion naturally tends toward low coupling because it is focused enough to not need many external dependencies.

Polymorphism

Definition: When behavior varies by type, use polymorphism (abstract classes, interfaces, method overriding) rather than conditionals.

Instead of asking "what type is this?" and branching with if-else or switch, define a common interface and let each type handle its own behavior.

// ❌ BAD: Type-checking with conditionals
class NotificationSender {
Future send(String type, String message, String recipient) async {

if (type == 'email') {
  await emailService.send(recipient, message);
} else if (type == 'sms') {
  await smsService.send(recipient, message);
} else if (type == 'push') {
  await pushService.send(recipient, message);
} else if (type == 'whatsapp') {
  await whatsappService.send(recipient, message);
}
// Adding Telegram? Modify this class again.

}
}

// ✅ GOOD: Polymorphism — each notification type handles itself
abstract class NotificationChannel {
Future send(String message, String recipient);
String get channelName;
}

class EmailNotification extends NotificationChannel {
@override
String get channelName => 'Email';

@override
Future send(String message, String recipient) async {

await emailService.send(recipient, message);

}
}

class SmsNotification extends NotificationChannel {
@override
String get channelName => 'SMS';

@override
Future send(String message, String recipient) async {

await smsService.send(recipient, message);

}
}

class PushNotification extends NotificationChannel {
@override
String get channelName => 'Push';

@override
Future send(String message, String recipient) async {

await pushService.send(recipient, message);

}
}

// Adding Telegram requires only a new class, nothing else changes
class TelegramNotification extends NotificationChannel {
@override
String get channelName => 'Telegram';

@override
Future send(String message, String recipient) async {

await telegramService.send(recipient, message);

}
}

class NotificationSender {
Future send(NotificationChannel channel, String message, String recipient) async {

await channel.send(message, recipient);

}
}

Pure Fabrication

Definition: When no natural domain class is a good fit for a responsibility, create an artificial class (a fabrication) to handle it.

Not everything in your system maps neatly to a real-world concept. Sometimes you need a class that exists purely for technical reasons: to keep other classes clean, to handle infrastructure concerns, or to encapsulate a behavior that does not belong anywhere else.

// The domain has User, Order, Product — real world concepts.
// But where does "send an HTTP request" belong? Nowhere in the domain.
// Create a fabrication.

// Pure Fabrication: HttpClient does not represent a real-world concept
// It exists purely to encapsulate HTTP communication concerns
class ApiHttpClient {
final String _baseUrl;
final Map<String, String> _defaultHeaders;

ApiHttpClient({

required String baseUrl,
required String authToken,

}) : _baseUrl = baseUrl,

    _defaultHeaders = {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $authToken',
    };

Future<Map<String, dynamic>> get(String path) async {

final response = await http.get(
  Uri.parse('$_baseUrl$path'),
  headers: _defaultHeaders,
);
return _handleResponse(response);

}

Future<Map<String, dynamic>> post(

String path,
Map<String, dynamic> body,

) async {

final response = await http.post(
  Uri.parse('$_baseUrl$path'),
  headers: _defaultHeaders,
  body: jsonEncode(body),
);
return _handleResponse(response);

}

Map<String, dynamic> _handleResponse(http.Response response) {

if (response.statusCode >= 200 && response.statusCode < 300) {
  return jsonDecode(response.body);
}
throw ApiException(
  statusCode: response.statusCode,
  message: response.body,
);

}
}

ApiHttpClient does not represent a person, a product, or an order. It is a fabrication that exists purely to manage HTTP communication so that data sources and repositories do not have to deal with raw HTTP details.

Indirection

Definition: Assign responsibility to an intermediate object to mediate between components, reducing direct coupling.

Indirection is about introducing a middleman that coordinates between two things that should not know about each other directly.

// ❌ BAD: Presentation directly depends on data layer
class UserProfileWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {

// Widget directly calling the database
final db = MySqlDatabase();
final user = db.query('users', 'user_123');
return Text(user['name']);

}
}

// ✅ GOOD: Indirection through repository and use case layers

// The repository is an indirection layer between use cases and the database
abstract class UserRepository {
Future<User?> findById(String id);
}

class UserRepositoryImpl implements UserRepository {
final Database _database;
UserRepositoryImpl(this._database);

@override
Future<User?> findById(String id) async {

final data = await _database.query('users', id);
return data != null ? User.fromJson(data) : null;

}
}

// The use case is an indirection layer between presentation and domain
class GetUserUseCase {
final UserRepository _repository;
GetUserUseCase(this._repository);

Future<Result<User, AppException>> execute(String userId) async {

final user = await _repository.findById(userId);
if (user == null) return Result.failure(AppException.notFound());
return Result.success(user);

}
}

// Widget depends only on the notifier — completely decoupled from data layer
class UserProfileWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {

final userState = ref.watch(userProfileProvider);
return userState.when(
  data: (user) => Text(user.name),
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Text('Error: $e'),
);

}
}

Each layer is an indirection point. The widget does not know about the repository. The repository does not know about the widget. The use case sits in between and coordinates without creating tight coupling between the extremes.

Protected Variations

Definition: Identify points of predicted variation or instability and assign responsibilities to create a stable interface around them.

Wrap the things most likely to change behind a stable abstraction. Code that is unlikely to change depends on the stable interface, not on the unstable detail.

// Payment providers change — Stripe today, Flutterwave tomorrow
// Protect everything that uses payment from this variation

abstract class PaymentGateway {
Future charge(double amount, String currency, String token);
Future refund(String transactionId, double amount);
}

// Stripe implementation — likely to change or be replaced
class StripeGateway implements PaymentGateway {
final String _apiKey;
StripeGateway(this._apiKey);

@override
Future charge(double amount, String currency, String token) async {

// Stripe-specific API calls
print('Stripe: charging $amount $currency');
return PaymentResult(transactionId: 'stripe_txn_001', success: true);

}

@override
Future refund(String transactionId, double amount) async {

print('Stripe: refunding $transactionId for $amount');

}
}

// Flutterwave implementation — could be swapped in with no changes to business logic
class FlutterwaveGateway implements PaymentGateway {
final String _publicKey;
FlutterwaveGateway(this._publicKey);

@override
Future charge(double amount, String currency, String token) async {

print('Flutterwave: charging $amount $currency');
return PaymentResult(transactionId: 'fw_txn_001', success: true);

}

@override
Future refund(String transactionId, double amount) async {

print('Flutterwave: refunding $transactionId for $amount');

}
}

// All business logic uses the stable PaymentGateway abstraction
// It is fully protected from the variation of which gateway is in use
class PaymentUseCase {
final PaymentGateway _gateway;
PaymentUseCase(this._gateway);

Future processPayment(double amount, String token) async {

return await _gateway.charge(amount, 'NGN', token);

}
}

Hard Object References: Stable Object References for Mutable Application State

Thu, 09 Jul 2026 08:53:05 +0000

In JavaScript and TypeScript, object references are often treated as disposable. An object is created, assigned to a variable, passed around, replaced, copied, spread, cloned, and eventually discarded.

That is normal language behavior, but in larger mutable systems it creates a specific class of bugs: stale aliases.

A stale alias appears when one part of the program still holds a reference to an old object while another part has already replaced that object with a new one. The old reference is still valid JavaScript, but it no longer points to current data.

Hard Object References is a discipline for avoiding that class of bugs.

The idea is simple:

Object and array references should be stable. Do not replace them as a normal update mechanism. Copy data into existing objects instead.

This rule is useful for application state, but it is not limited to global stores. It applies to ordinary variables, local component state, nested fields, arrays, drafts, snapshots, runtime models, and temporary objects.

The broader principle is:

Replace primitive values. Do not replace object and array references.

The First Rule: `const` for Objects and Arrays

The first level is variable bindings.

If a variable holds an object or array, it should normally be declared with const:

const user = { /* ... */ };

const items = [ /* ... */ ];

not:

let user = { /* ... */ };

let items = [ /* ... */ ];

The point is not that the object becomes immutable. It does not.

This is still possible:

user.name = 'Alex';
items.push(nextItem);

The point is that the variable should not be rebound to a different object:

user = nextUser;
items = nextItems;

That replacement changes which object the variable points to. Any other code that still holds the old reference now points to obsolete data.

So the first rule is:

Use const for object and array references. Mutate or copy data into the object. Do not rebind the reference.

This rule also applies to temporary objects. A temporary object may be short-lived, but while it exists, its reference should still be stable.

The Stale Alias Problem

Consider this code:

const user = {
    name: 'John',
    address: {
        city: 'Paris',
        street: 'Main'
    }
};

const address = user.address;

Now another part of the code replaces the nested object:

user.address = {
    city: 'Berlin',
    street: 'Main'
};

After this assignment:

address === user.address; // false

The variable address still points to a valid object, but it points to obsolete data.

That is the dangerous part. The program does not necessarily crash. It continues to operate on the wrong object.

A Hard Object References approach avoids the replacement:

HardObject.set(user.address, {
    city: 'Berlin'
});

address === user.address; // true
address.city; // 'Berlin'

The reference stayed stable. The data changed.

Temporary Objects Are Not an Exception

A temporary object is not an excuse to use unstable references.

This is fine:

const draft = {
    // ...
};

HardObject.set(draft, {
    name: 'Alex',
    address: {
        city: 'Berlin'
    }
});

This is suspicious:

let draft = {
    // ...
};

draft = {
    name: 'Alex',
    address: {
        city: 'Berlin'
    }
};

The object may be temporary, but rebinding the reference still breaks the same mental model.

If a temporary object needs new data, copy the data into it:

HardObject.set(draft, nextDraftData);

not:

draft = nextDraftData;

This matters because temporary objects often become inputs to state updates:

const draft = {
    // ...
};

HardObject.set(draft, formData);
HardObject.set(state.user, draft);

The draft is not necessarily installed application state, but it still follows the same reference discipline.

So the stronger rule is:

The reference-stability discipline applies to objects in general. Application state is where violating it becomes most expensive.

Application State Makes the Rule Critical

In small local code, replacing an object may be harmless.

In application state, the same operation becomes dangerous because many parts of the program may retain references to the same object:

const selectedAddress = state.user.address;
const editorTarget = state.user.address;
const validationTarget = state.user.address;
const renderTarget = state.user.address;

If this happens later:

state.user.address = nextAddress;

all previous references may become stale.

This is why Hard Object References is especially important for state graphs:

state.user
state.user.address
state.settings
state.document
state.document.pages
state.selection

These are not just values. They are live reference nodes.

Once an object participates in such a graph, replacing its reference should not be the normal update mechanism.

From Principle to Utility

The principle can be followed manually:

const state = {
    // ...
};

HardObject.set(state.user, nextUser);
HardObject.set(state.settings, nextSettings);
HardObject.set(state.items, nextItems);

But a consistent helper can make the rule explicit.

For explanation, call that helper HardObject.

HardObject is not the principle itself. It is only one possible way to express the principle:

const state = HardObject.create(rawState);

The purpose of HardObject.create() is to install an object graph under a hard-reference contract.

The matching update operation is:

HardObject.set(state.user, nextUser);

This means:

Copy compatible data from nextUser into state.user without replacing object or array references.

So the conceptual pair is:

const state = HardObject.create(rawState);

HardObject.set(state.user, nextUser);

create() establishes the hard-reference boundary.
set() updates data inside that boundary.

Type-Level Installation

In the simplest implementation, HardObject.create() can be only a TypeScript-level identity function.

At runtime, it may simply return the same object:

class HardObject {
    public static create<T>(value: T): Hard<T> {
        return value as Hard<T>;
    }
}

The value is returned as-is, but TypeScript can expose it as a type where object and array references are readonly.

A simplified type could look like this:

type Primitive =
    | string
    | number
    | boolean
    | bigint
    | symbol
    | null
    | undefined;

type Hard<T> =
    T extends Primitive
        ? T
        : T extends Array<infer TItem>
            ? ReadonlyArray<Hard<TItem>>
            : {
                readonly [TKey in keyof T]: Hard<T[TKey]>;
            };

This version is intentionally simplified. A real implementation may use a more refined type where primitive fields remain writable while object and array references become readonly.

The architectural point is:

HardObject.create() gives the object graph a hard-reference contract.

That contract can start as TypeScript-only. Later, it can add runtime enforcement without changing the call site.

Runtime Enforcement

TypeScript can catch many mistakes during development, but it does not enforce the rule at runtime.

If runtime enforcement is needed, HardObject.create() can recursively walk the object graph.

Whenever it finds a property whose value is an object or array, it can make that property non-writable on its parent object:

Object.defineProperty(target, key, {
    value,
    writable: false,
    configurable: false,
    enumerable: true
});

Then it continues recursively into that nested object or array and applies the same rule to its children.

The developer does not manually lock every nested property. HardObject.create() is the centralized installation point.

So HardObject.create() can evolve in stages:

Stage	Runtime behavior	Purpose
Type-only	Returns the same object	Provides a TypeScript hard-reference contract
Runtime-enforced	Recursively locks object/array fields	Prevents object-reference replacement at runtime
Framework adapter	Installs the graph into a reactive/store system	Integrates with a specific environment

The rule is not:

Nothing can change.

The rule is:

Primitive values may change. Object and array references should remain stable.

So this is a normal update:

state.user.name = 'Alex';
state.user.address.city = 'Berlin';

But this is not:

state.user.address = {
    city: 'Berlin',
    street: 'Main'
};

The address reference is hard.

The correct update path is:

HardObject.set(state.user, {
    address: {
        city: 'Berlin'
    }
});

Updating a Hard Object Graph

HardObject.set() is a copy-in operation:

HardObject.set(state.user, {
    name: 'Alex',
    address: {
        city: 'Berlin'
    }
});

It means:

Copy compatible data from the source object into the target object without replacing object and array references.

Primitive fields can be assigned directly:

name: 'Alex'

Nested objects are updated recursively:

address.city = 'Berlin'

But the address object itself is not replaced.

Arrays follow the same principle: the array reference remains stable, while its contents are updated through controlled logic.

The exact implementation can vary. HardObject may be a utility, a base class, a model method, a store helper, or a framework-specific adapter. The concept is lower-level than any one implementation.

Change Tracking

A common objection is:

If references do not change, how do you detect changes?

The answer depends on the environment.

In a reactive system, reference replacement does not have to be the primary change signal. If primitive fields and nested object properties are reactive, then normal mutation tracking can already observe changes inside the stable object graph.

For example, in Vue or a similar reactive system, a deep watcher, computed dependency, proxy trap, or framework-level reactive effect may observe this operation:

HardObject.set(state.user, {
    name: 'Alex',
    address: {
        city: 'Berlin'
    }
});

The reference stays stable, but reactive property writes still occur.

In that case, HardObject.onChange() may not be necessary. The reactive system already provides change tracking.

In a non-reactive system, HardObject can provide a simple explicit notification mechanism:

HardObject.onChange(change => {
    // mark dirty, update UI, notify observers, sync state, etc.
});

HardObject.set() can emit a change only if it actually changed at least one value. If the incoming data is equal to the current data, no change event is needed.

So the rule is:

Do not require object replacement to be the change signal.

Use the mechanism that fits the environment: framework reactivity, deep watchers, proxy-based tracking, explicit events, dirty flags, version counters, or observers.

Hard Object References only says that object references should remain stable. It does not prescribe one universal change-tracking system.

Contrast with Immutable State

Immutable update style treats state as a value. Updating state usually means producing a new object graph:

const nextState = {
    ...state,
    user: {
        ...state.user,
        name: 'Alex'
    }
};

Reference replacement is intentional. Changed references are used to detect changed branches.

Hard Object References uses a different model:

HardObject.set(state.user, {
    name: 'Alex'
});

The object remains the same. Its data changes.

The central contrast is:

In immutable systems, references are change signals.
In Hard Object References, references are stable addresses.

Comparison

Topic	Immutable Update Style	Hard Object References
Main model	State as value	State as object graph
Update mechanism	Produce new state	Copy into existing graph
Object binding	May be replaced	Prefer `const` for object/array references
Object field replacement	Normal	Forbidden or controlled
Object identity	Often disposable	Stable
Nested references	Commonly replaced	Preserved
Change signal	Reference change	Reactivity, event, dirty flag, version counter, observer
Best fit	Serializable state, reducers, snapshots	Complex mutable runtime state
Main risk	Stale captured old state	Uncontrolled mutation

Neither model is universally better.

Immutable updates are excellent when state is mostly plain data and the architecture benefits from treating every update as a value transformation.

Hard Object References is useful when state is a mutable object graph and references are used as live handles.

Where This Works Well

Hard Object References fits systems where object references are retained and reused over time:

complex frontend state
large component-local state
document editors
visual editors
reader engines
graph editors
timeline editors
canvas or layout tools
class-based domain models
runtime controllers
selection models
render pipelines
async processes that keep object handles

The boundary is not global state versus local state.

A large component with complex internal state can suffer from the same stale-reference problems as an application-level store. If nested objects are passed around inside that component and later replaced, local aliases can become obsolete too.

The real boundary is:

Can another piece of logic keep this object reference and later expect it to remain current?

If yes, the reference should usually be hard.

When This Rule Is Less Important

This discipline is less critical for:

primitive values
short-lived scalar calculations
small isolated functions
pure transformation pipelines
immutable reducer-based architectures
throwaway objects that never escape their local scope

Even in these cases, the rule can still be useful as a default bias, because reference stability depends on a question that is often hard to answer upfront:

Can this reference escape, be retained, or become obsolete after replacement?

Benefits

The main benefit is not less code. The main benefit is a stronger state invariant.

Object references remain valid.

Retained object handles do not silently become obsolete.

Nested state ownership becomes clearer.

Debugging gets a simple rule:

If an object reference changed, something violated the reference discipline.

This is especially useful in systems where many subsystems interact with the same mutable object graph.

Costs

The costs are real.

Mutation must be controlled. If every part of the application mutates everything freely, the system becomes unstable.

Change tracking must exist. In reactive systems, this may already be handled by the framework. In non-reactive systems, it may require explicit events, observers, dirty flags, or version counters.

The approach is also less natural for tooling built around immutable snapshots, reducer replay, time travel, and structural sharing.

Hard Object References is not a replacement for immutable architecture in every application. It is a different tradeoff for a different kind of state.

Conclusion

Hard Object References treats object references as stable addresses, not disposable values.

The rule starts with mandatory use of const with objects and arrays and continues inside object graphs:

HardObject.set(user.address, nextAddress);

not:

user.address = nextAddress;

A utility such as HardObject can make the rule explicit. HardObject.create() establishes a hard-reference contract. It can start as a type-level identity function and later add runtime enforcement without changing the call site. HardObject.set() updates the graph by copying data into existing references.

This is not presented as a newly invented universal pattern. The underlying concerns are old: object identity, aliasing, ownership, mutation control, and stable object graphs. Hard Object References is my practical formulation of those concerns after repeatedly seeing the same class of bugs in mutable applications: references becoming obsolete because some part of the object graph was replaced instead of updated.

In my own code, this discipline became a stability rule. It reduces Heisenbug-like behavior where the program still runs but some logic works with a detached object. It also changes the mental model: objects are no longer disposable containers that can be swapped at any level. They become stable addresses, and updates become explicit data transfer into those addresses.

The core rule is:

Replace primitive values. Do not replace object and array references.

Or shorter:

References are not change signals. They are stable addresses.

🏗️✨ The SOLID Principles: 5 Golden Rules for Super Code! 💎🧒

Tue, 09 Jun 2026 15:11:07 +0000

(Continuing our Magical Toy Workshop adventure! 🧸🏭)

Grandpa Maker's workshop was thriving, but as more toys were created, things got tricky! 🔧😅
Blueprints tangled, upgrades broke old toys, and swapping parts was a puzzle. 🌀
So Grandpa carved 5 Magical Rules into the workshop door. He called them SOLID — the secret to building toys (and code!) that are strong, flexible, and easy to love! 💙🚀

Let's unlock each rule with a story! 🗝️📖✨

🔤 What Does SOLID Mean?

SOLID is an acronym for 5 design principles that help programmers write clean, maintainable code. 🧹💻
In our workshop, they help Grandpa build toys that are: ✅ Easy to fix 🔧
✅ Simple to upgrade 🆙
✅ Fun to extend 🎨
✅ Safe to share 🤝

🎯 S – Single Responsibility Principle (SRP)

"One toy, ONE special job!" 🧸✨

The Story:
Grandpa once built a "Mega-Bot 3000" that could:
🎨 Paint • 🚗 Drive • 🎵 Sing • 🍪 Bake • 🌈 Dance

But… paint got in the cookies 🎨🍪, singing scared the car 🎵🚗, and everything broke at once! 😫

The Fix:
🔹 Painter Bot → only paints 🎨
🔹 Driver Bot → only zooms 🏎️
🔹 Chef Bot → only bakes 🧑🍳

💡 In Code:
A class should have only one reason to change. Keep it focused! 🎯
Example: class CookieOven should bake cookies — not also deliver mail! 📬❌

📦🔓 O – Open/Closed Principle (OCP)

"Open for upgrades, closed for breakage!" 🌈🛡️

The Story:
The race car blueprint was perfect! 🏎️✨ But kids wanted:
🌙 Glow wheels • 🌈 Rainbow paint • 🚀 Turbo boost

Instead of rewriting the whole plan (and risking breaks! 😰), Grandpa added snap-on modules! 🧩✅
Core car = safe & closed 🔒
Add-ons = easy & open 🔓

💡 In Code:
Classes should be open for extension (new features) but closed for modification (don't break old code).
Example: Use interfaces or inheritance to add GlowWheelModule without touching RaceCar! 🛠️✨

🔄🧩 L – Liskov Substitution Principle (LSP)

"New versions must fit the old slots!" 🎮✅

The Story:
The garage had a "Toy Car" parking spot 🅿️.
🚗 Regular Car → fits perfectly!
🚀 Hover Car → floats away! 😱 Doesn't follow the same rules!

Grandpa fixed it: Every new car must work wherever the original car works.
Now Hover Car still uses the same remote, same garage, same tracks — just with extra magic! ✨🛤️

💡 In Code:
If class Duck has a quack() method, then class RubberDuck shouldn't throw an error when quack() is called! 🦆🔇
Subtypes must be substitutable for their base types. 🔄✅

📋✂️ I – Interface Segregation Principle (ISP)

"Only the instructions you actually need!" 🧩📖

The Story:
Grandpa once gave EVERY toy the same giant manual:
fly() ✈️ • swim() 🏊 • hug() 🤗 • zoom() 🏎️ • bark() 🐶

Teddy Bear stared at fly()… 🧸✈️❓
Fish looked at hug()… 🐠🤗❓
So confusing! 😵

The Fix: Split the manual into tiny, focused sheets! 📄✨
🐻 Bear Manual → hug(), sit()
🚁 Copter Manual → fly(), land()
🐠 Fish Manual → swim(), splash()

💡 In Code:
Don't force classes to depend on methods they don't use. 🙅♂️
Many small, specific interfaces > one big, messy one. 🧩✅

🔌🔗 D – Dependency Inversion Principle (DIP)

"Plug into standards, not specifics!" 🔋🔌

The Story:
Robots only worked with the rare "Zap-Battery 3000" ⚡🔋.
When it ran out… 🤖💤 Everything stopped! 😱

Grandpa changed the design:
🔹 Instead of: "Robot needs Zap-Battery 3000"
🔹 He wrote: "Robot needs ANY battery with a Standard Power Slot" 🔌✨

Now:
🔋 Alkaline • 🔋 Solar • 🔋 Magic Crystal — all click in! 🎉

💡 In Code:
Depend on abstractions (interfaces/abstract classes), not concrete implementations.
High-level modules shouldn't depend on low-level details — both should depend on abstractions. 🌉✨

🌟 SOLID Quick-Reference Chart 🗂️✅

Letter	Principle	Toy Workshop Wisdom	Code Superpower
S	Single Responsibility	🎯 One toy, one job	Easier to test & fix
O	Open/Closed	📦 Add snap-ons, don't rewrite	Safe upgrades
L	Liskov Substitution	🔄 New toys fit old slots	Reliable swapping
I	Interface Segregation	📋 Small manuals, no confusion	Clean, focused contracts
D	Dependency Inversion	🔌 Standard slots, any battery	Flexible, decoupled design

🎁 Why SOLID Matters for Kids (and Grown-Up Coders!) 🧒👩💻

✨ Less Breaking – Toys (and apps!) stay fun longer! 🧸🔧
✨ Easier Sharing – Friends can add to your blueprint without mess! 🤝📐
✨ Happy Debugging – When something breaks, you know exactly where to look! 🔍✅
✨ Future-Proof – New ideas snap right in! 🚀🌈

🧙♂️ Grandpa's Final Wisdom:
"SOLID isn't about perfect code on day one.
It's about building with love, so your creations can grow, adapt, and bring joy — today, tomorrow, and always." 💙🏭✨

Now YOU know the secret rules behind the world's best toys… and the world's best software! 🎮💻🧸
Ready to design your own SOLID masterpiece? Grab your imagination, pick a principle, and start building! 🚀📐💫

(Workshop.status() → "SOLID & Sparkling!" ✅🌟)

The Magical Toy Workshop: A Story About OOP 🧸🏭✨

Tue, 09 Jun 2026 14:56:26 +0000

Once upon a time, in a cozy little town, there was a very special place called The Blueprint Workshop 📐✨.
Every day, Grandpa Maker drew up plans to bring toys to life. But he didn’t build them one by one from scratch… he used a clever trick called Object-Oriented Programming (OOP)! 💻🎈
Let’s peek inside and see how it works!

📜 The Magic Blueprint = Class

Grandpa didn’t start with glue and paint. He started with a blueprint! 🗺️ A blueprint is just a set of instructions that says: “If you want to make this toy, here’s exactly how it should look and what it should know.” In OOP, we call this a Class. 🏗️✨

🤖🧸🚗 The Real Toys = Objects

When Grandpa followed the blueprint and pressed the 🟢 “Make!” button… POOF! 🎩💨 A real toy appeared! Each actual toy is called an Object. The blueprint is just paper, but the object is the real, huggable, zoomable thing you can play with! 🌈🧸

🎨⚙️ What the Toy Has = Attributes

Every toy comes with special features. We call these Attributes (or Properties). 📝
The race car 🏎️ has: color = red, wheels = 4, speed = fast
The teddy bear 🧸 has: fur = soft, size = cuddly, favorite_hug = warm
Attributes are like a toy’s personality card! 🃏✨

🎵💃 What the Toy Can Do = Methods

Toys aren’t just for looking at… they do things! In OOP, we call these actions Methods. 🛠️
car.zoom() 🏁
bear.hug() 🤗
robot.dance() 🕺
Methods are the toys’ superpowers that you can call by name! ⚡

🔒📦 Keeping Secrets Safe = Encapsulation

Some parts of the toys are very delicate, like their tiny batteries 🔋 or magic gears ⚙️. Grandpa wraps them up in a little box so little fingers don’t accidentally break them. 🔐 This is called Encapsulation! Only the toy itself knows how to use its insides. You just press the button, and it works! 🎛️✅

One day, Grandpa made a Super Robot 🤖 that could walk(), talk(), and lift(). Then he wanted a mini-robot! Instead of starting over, he made the little one a child of the big robot. 🧬✨ The mini-robot automatically knew how to walk(), talk(), and lift() too! Then he added his own trick: spin(). 🌀 This family sharing is called Inheritance. Parents pass down abilities, kids add new ones! 👨👦💫

🎭🔄 Same Command, Different Magic = Polymorphism

The workshop had a special button labeled PLAY ▶️. When you press it…
🥁 The drum says bang!
🚗 The car says zoom!
🧸 The bear says hug!
🤖 The robot says beep-boop-dance!
Same button, totally different responses! ✨ This clever trick is called Polymorphism (poly = many, morph = forms). It lets every toy answer the same request in its own special way! 🎶🌈

🌫️🔍 You Don’t Need to Know Every Gear = Abstraction

You never have to open the toy to see how the springs and wires work. 🙈 You just press a button, and magic happens! 🪄 In OOP, this is Abstraction: hiding the messy details and only showing you what you actually need to use. Clean, simple, and stress-free! 🧘♂️✨

🧩 The Happy Ending 🏁💖

And that’s how the Blueprint Workshop builds amazing playmates using OOP! 🧸🏎️🤖

📜 Class = the plan
🎁 Object = the real toy
🎨 Attributes = what it has
🎵 Methods = what it does
🔒 Encapsulation = safe secrets
🌳 Inheritance = family superpowers
🎭 Polymorphism = same call, different magic
🌫️ Abstraction = simple buttons, hidden gears

Now you know the secret language of toy makers… and computer programmers too! 👾💻✨
Want to design your own class someday? Grab your imagination, draw a blueprint, and press Make! 🚀🧒💙

(The end… or should we say, story.end()? 😉📖✨)

DevLog 20260319: Towards OOP - Document-Level Default Module and Module-Level Members and Behaviors

Thu, 19 Mar 2026 20:31:07 +0000

Revisiting Flappy Bird – The Pain Point

Remember our Flappy Bird example from mid-2025?

The long chain of variable initializations was needed for two main reasons:

No way to declare variables before using them
More critically - no way to define custom data structures that could group related values together and be instantiated with a single node.

In retrospective it seems obvious: we just need proper structured data containers. But building the scaffolding to support this properly in a visual, node-based system is a bit more involved.

Searching for a Solution

I spent a long time trying to bring OOP concepts into Divooka. A huge amount of effort went into DiOS (Divooka Open Standards), with the hope that a complete standard would naturally solve these kinds of problems. But standardization work is slow and deep - just like making Divooka itself feature-complete.

Then, while working on something completely unrelated and taking a short break from this topic, it suddenly clicked.

The key insight: start simple and approach it from a functional/declarative angle first, before jumping into inheritance, encapsulation, polymorphism, and all those good stuff.

I'm really excited - we finally have meaningful progress.

The Divooka Way

To claim our goal as "everything is a node" is a bit too strong, but I strongly prefer keeping almost everything on the graph.

This aligns with how we already handle structured primitives - direct value setting of compound inputs. That way, there's still hope that users can drop down to raw node programming when they need full control (and thus keep everything programmable).

Traditional property panels (like Unreal Blueprints' object definition GUIs) are out - they break the pure graph paradigm.

Instead, the solution is declarative, similar to how TerraGen works: the mere presence and connection of certain nodes defines meaning.

This feels awesome for several reasons:

We can make full use of the 2D graph layout - place things exactly where we want them visually
It stays completely coherent with Divooka's graphical paradigm
No need for separate "class editor" UIs

What's Been Implemented So Far

Current working pieces:

Graphs can now act as modules
Support for module-level data members and behavior members
A main module tied to the document, with existing graphs serving as associated behaviors

Module-scoped instance node – in Events context

Module-scoped instance node – in Dataflow context

Top-level module behavior graphs

This immediately unlocks:

Clean access to (top-level) module instances
Shared event and dataflow instance data
A unified programming and document model for subgraphs (still a work-in-progress)
In procedural contexts (Glaze! especially): we now have proper data containers - no more awkward giant variable lists or forced tuples! (Compare to the old Flappy Bird screenshot)
Much simpler and more natural state storage/access in Glaze! and procedural graphs

This is a big deal - for a system that's gearing up for real production use, it feels like crossing a major milestone in usefulness and core abstractions.

Current Limitations & Remaining Work

Still plenty to fix/polish:

A bunch of bugs and edge cases
Proper serialization support
Smooth context switching between graphs
Subgraph consolidation / better nesting UX

Looking Ahead

This is a solid foundation, but there's still a long road:

Full modularization support
Modules inside modules (nesting)
Module inheritance / composition patterns / polymorphism
Base DOM exposed as the "main module" for metaprogramming API
Detailed documentation: how it all fits together, recommended usage patterns, expected behaviors, pitfalls
Module-level scoped instances (deeper/finer control)

Overall - I am very happy with the direction. It feels like Divooka is finally getting the abstraction power it deserves while staying true to its visual, graph-first philosophy.

I am hyped for what we will achieve.

References

When and Why to Rewrite OOP Code in Functional Style

Sat, 05 Jul 2025 19:31:02 +0000

When and Why to Rewrite OOP Code in Functional Style

Rewriting a large object-oriented programming (OOP) codebase into a functional programming (FP) style is a bold and often controversial move in software engineering. While the challenges are significant—including a steep learning curve, possible disruptions to productivity, and the complexity of transitioning a live system—the rewards can be equally transformative. Under the right circumstances, refactoring OOP code into a functional paradigm can bring enhanced maintainability, scalability, and even performance gains to your system. In this article, we’ll explore when such a rewrite makes sense, the benefits it offers, and the key considerations you must account for.

This deep dive is intended for software architects, senior developers, and engineering managers who are contemplating or currently planning a paradigm shift in their software systems. We’ll detail the scenarios where this shift is not only justified but potentially game-changing.

Understanding the Philosophical Divide: OOP vs Functional Programming

Before diving into the "when" and "why," it's essential to understand what distinguishes these two paradigms. Object-Oriented Programming organizes code around objects—collections of data and behavior—relying heavily on inheritance, polymorphism, and encapsulation. It's widely used and deeply entrenched in enterprise-level applications, particularly in languages like Java, C++, and C#.

Functional Programming, on the other hand, emphasizes pure functions, immutability, and declarative code. Rather than modifying state, FP favors data transformations. Languages like Haskell, Elixir, and Clojure embody this approach, though functional styles can also be adopted in modern multi-paradigm languages such as Python, JavaScript, Kotlin, Scala, and even Java.

These two paradigms don’t just differ in syntax; they represent fundamentally different ways of thinking about problems and solutions. Shifting from OOP to FP is like switching from building blueprints to designing ecosystems—each approach has its strengths and limitations.

Scenario 1: Taming Complex State Management

One of the most compelling reasons to move from an object-oriented to a functional codebase is to reduce the complexity of state management. In large systems, tracking state mutations across deeply nested objects and shared mutable data can become nearly impossible, leading to elusive bugs and maintenance nightmares.

Functional programming enforces immutability and encourages the use of pure functions, which do not rely on or modify external state. This significantly simplifies reasoning about code. When each function has a clear input and output with no side effects, debugging and testing become much easier. Systems that previously required complex mocking and integration tests can now be validated with straightforward unit tests.

For systems where state changes are a constant source of bugs—such as real-time applications, distributed systems, or financial transaction platforms—a functional rewrite can lead to dramatic improvements in both reliability and maintainability.

Scenario 2: Scaling for Concurrency and Parallelism

Modern applications must often scale across multiple processors or even distributed clusters. Object-oriented codebases often struggle in this regard because shared mutable state introduces race conditions and makes concurrency error-prone. Even with synchronization mechanisms like locks or semaphores, the risk of deadlocks, resource contention, and performance bottlenecks remains high.

Functional programming offers a better fit for concurrent execution. Since functions avoid side effects and data is immutable, operations can be safely executed in parallel. Frameworks like Akka (for Scala) or Elixir’s OTP harness functional principles to achieve fault-tolerant concurrency at scale.

If your application must support thousands of simultaneous users, handle parallel data streams, or interact with asynchronous services, rewriting critical portions in a functional style can drastically improve performance and reliability.

Scenario 3: Reducing Technical Debt in Legacy Systems

Legacy codebases often evolve into monoliths riddled with tight coupling, hidden dependencies, and tangled inheritance hierarchies. As features are bolted on over years, the system becomes brittle and resistant to change—a state commonly referred to as technical debt.

Functional programming encourages modularity, composition, and stateless design, which naturally lead to codebases that are easier to maintain and extend. Functions can be reused without worrying about the side effects of hidden states. When dealing with a legacy OOP system that’s becoming too costly to maintain, a functional rewrite—even partial—can serve as a strategic investment that reduces long-term costs.

It’s worth noting that such rewrites can be done incrementally. Many languages support both paradigms, allowing for gradual adoption. For example, teams working in JavaScript can begin using functional libraries like Ramda or Lodash/fp before committing to a full architectural overhaul.

Scenario 4: Improving Testability and Reliability

Testing object-oriented systems often requires mocking complex objects, managing dependency injection, and simulating state changes—all of which can make writing tests a laborious process. This overhead frequently leads to insufficient test coverage and increased risk of bugs in production.

In contrast, functional code is naturally testable. Pure functions can be tested with simple input/output comparisons, and the absence of side effects means there’s no need for elaborate setup or teardown routines. As a result, teams can achieve higher test coverage with less effort.

Rewriting parts of an OOP system into a functional style can thus be a strategic move to increase confidence in the system’s correctness, reduce bugs, and streamline continuous integration processes.

Scenario 5: Preparing for Domain-Driven Design (DDD)

Domain-Driven Design seeks to model complex domains in a way that reflects real-world business logic. While traditionally associated with OOP, DDD principles—like bounded contexts, aggregate roots, and domain events—also map well to functional programming.

In fact, functional languages can provide better abstraction tools for modeling business logic due to their emphasis on algebraic data types, pattern matching, and immutability. These features make it easier to write clear, intention-revealing code that’s resistant to misuse and logically consistent.

Organizations looking to modernize their architecture by adopting DDD may find a functional approach not just compatible but actually advantageous.

Scenario 6: Enhancing Developer Productivity and Onboarding

While functional programming has a reputation for a steep learning curve, once developers become proficient, productivity often increases. Code tends to be shorter, more predictable, and less error-prone. Additionally, functional code encourages declarative thinking, which can reduce cognitive load.

In a large OOP codebase, new developers may struggle to understand the intricate class hierarchies and implicit behaviors. By contrast, a well-structured functional codebase offers smaller, composable units that are easier to grasp in isolation.

If your team is experiencing high turnover or scaling rapidly, a shift to a functional codebase could reduce onboarding time and improve code quality across the board.

Scenario 7: Enforcing a More Disciplined Codebase

In OOP, discipline is often left to the developer. It’s possible—and common—to misuse inheritance, allow state to leak, or create “god objects” that violate separation of concerns. Functional programming is more restrictive by nature, which can be a blessing in disguise.

By enforcing immutability, discouraging side effects, and promoting composition, a functional style nudges developers toward better practices. This built-in discipline reduces the room for error and makes it easier to enforce architectural standards across teams.

In large organizations where code quality and consistency are critical, this can lead to more maintainable and scalable systems over the long run.

Strategic Considerations Before Rewriting

Despite the benefits, rewriting an entire codebase is risky. It’s time-consuming, potentially disruptive, and can introduce regressions if not done carefully. Before committing, it’s crucial to conduct a cost-benefit analysis and determine whether the gains from functional programming justify the investment.

Often, a full rewrite isn’t necessary. Instead, consider refactoring specific modules—especially those with critical bugs, performance bottlenecks, or architectural issues—into a functional style. This hybrid approach allows teams to test the waters and gain experience before committing more fully.

It’s also essential to ensure that your development team has—or is willing to acquire—the necessary skills. Functional programming introduces concepts like higher-order functions, monads, and recursion that may be unfamiliar to developers with a purely OOP background. Investing in training and mentorship is key to a successful transition.

Tools and Languages That Support Functional Refactoring

Thankfully, many modern languages are multi-paradigm and support functional features natively. JavaScript, for example, has first-class functions and libraries like RxJS and Ramda. Kotlin offers powerful FP constructs like data classes, extension functions, and coroutines. Even Java has introduced functional features such as streams and lambdas in recent versions.

This means you don’t necessarily need to switch languages to adopt a functional approach. Instead, you can evolve your architecture gradually, leveraging functional principles where they make the most sense.

For teams starting from scratch, languages like Scala, Elixir, or F# may offer a more idiomatic experience. These languages are designed with FP in mind and provide robust ecosystems for building scalable, maintainable applications.

Real-World Success Stories

Companies like Twitter, Netflix, and Walmart have incorporated functional programming into their tech stacks to varying degrees. Twitter famously moved from Ruby on Rails to Scala to handle concurrency at scale. Netflix uses functional programming principles in its microservices architecture, leveraging RxJava and other reactive tools.

These case studies demonstrate that FP is not just academic theory—it’s being used in production to solve real-world problems at scale. For teams facing similar challenges, these examples offer both inspiration and proof of viability.

Final Thoughts

Rewriting a large object-oriented codebase in a functional style is not a decision to be taken lightly. It involves risk, effort, and a fundamental shift in how developers think about software. But under the right conditions—such as managing complex state, scaling for concurrency, or reducing technical debt—it can offer substantial rewards.

The key is to approach the transition strategically. Start small, focus on high-impact modules, invest in training, and adopt a hybrid model if needed. With careful planning and the right mindset, functional programming can become a powerful tool in your software engineering arsenal.

Coder Legion - Recent posts tagged oop

From Anemic Models to Rich Domain Models, DDD Base Entities, and C# Records

Part 1: The Anti-Pattern (Anemic Models & DTO Misuse)

The Problematic Approach

Why Anemic Models Fail

Part 2: DDD Foundation — Entity Base Class & C# Records

1. DDD Entity Base Class

2. C# Records for Value Objects

Part 3: Combining Interfaces, Abstract Classes, and DDD Entities

Part 4: The Rich Domain Model (Order)

Part 5: Orchestrating with SRP and Dependency Injection

Part 6: Persistence with EF Core (Mapping Records & TPH)

Part 7: Unit Testing with Records & Entities

References & Further Reading

The Art of Object-Oriented Programming

Classes & Objects

State, Behavior & Identity

The Four Pillars — What They Actually Mean

Encapsulation

Abstraction

Inheritance

Polymorphism

Composition vs. Inheritance — The Choice Nobody Teaches Properly

Association, Aggregation & Composition

Coupling & Cohesion — The Two Dials

Common OOP Design Mistakes

A Small Real-World Example

Conclusion: OOP as a Design Mindset

References

Find me across the web:

The Object-Oriented Design Handbook: SOLID, GRASP, and the Principles That Make Software Scale

Hard Object References: Stable Object References for Mutable Application State

The First Rule: const for Objects and Arrays

The Stale Alias Problem

Temporary Objects Are Not an Exception

Application State Makes the Rule Critical

From Principle to Utility

Type-Level Installation

Runtime Enforcement

Updating a Hard Object Graph

Change Tracking

Contrast with Immutable State

Comparison

Where This Works Well

When This Rule Is Less Important

Benefits

Costs

Conclusion

🏗️✨ The SOLID Principles: 5 Golden Rules for Super Code! 💎🧒

🔤 What Does SOLID Mean?

🎯 S – Single Responsibility Principle (SRP)

📦🔓 O – Open/Closed Principle (OCP)

🔄🧩 L – Liskov Substitution Principle (LSP)

📋✂️ I – Interface Segregation Principle (ISP)

🔌🔗 D – Dependency Inversion Principle (DIP)

🌟 SOLID Quick-Reference Chart 🗂️✅

🎁 Why SOLID Matters for Kids (and Grown-Up Coders!) 🧒👩💻

The Magical Toy Workshop: A Story About OOP 🧸🏭✨

📜 The Magic Blueprint = Class

🤖🧸🚗 The Real Toys = Objects

🎨⚙️ What the Toy Has = Attributes

🎵💃 What the Toy Can Do = Methods

🔒📦 Keeping Secrets Safe = Encapsulation

🌳👨👧👦 Sharing Family Traits = Inheritance

🎭🔄 Same Command, Different Magic = Polymorphism

🌫️🔍 You Don’t Need to Know Every Gear = Abstraction

🧩 The Happy Ending 🏁💖

DevLog 20260319: Towards OOP - Document-Level Default Module and Module-Level Members and Behaviors

Revisiting Flappy Bird – The Pain Point

Searching for a Solution

The Divooka Way

What's Been Implemented So Far

Current Limitations & Remaining Work

Looking Ahead

References

When and Why to Rewrite OOP Code in Functional Style

When and Why to Rewrite OOP Code in Functional Style

Understanding the Philosophical Divide: OOP vs Functional Programming

Scenario 1: Taming Complex State Management

Scenario 2: Scaling for Concurrency and Parallelism

Part 4: The Rich Domain Model (`Order`)

The First Rule: `const` for Objects and Arrays