DEV Community: Charles Koffler

A Semantic Approach to WPF and MVVM with Clprolf framework

Charles Koffler — Sat, 13 Jun 2026 17:10:32 +0000

Introduction

WPF and the MVVM (Model-View-ViewModel) pattern are powerful tools for desktop development. However, as applications grow, the technical plumbing—commands, data binding, notifications—can sometimes cloud the architectural intent. We can easily lose track of the conceptual meaning of our classes behind their technical implementations.

To bring more clarity to my desktop architectures, let's try a lightweight framework Clprolf. The goal is simple: use basic custom C# attributes to give every class a clear, human-readable role, and enforce these boundaries with automated architecture tests using ArchUnitNET.

Here is how it looks in practice.

The Core Concepts: Agents and Workers

Instead of categorizing code strictly by technical layers, Clprolf looks at the application as a team of actors working together:

Agents: Core components that carry an identity, state, representation, or behavioral intention.
Workers: Quiet executors or infrastructure tools that handle background or mechanical tasks.

When applied to WPF and MVVM, the system naturally organizes into three distinct types of Agents:

Domain Agents (User): The pure business entities holding the core data and identity.
Presentation Agents (UserViewModel): The ambassadors between the user and the system, orchestrating data and validating user intentions.
System-Oriented Agents (UserWindow & RelayCommand): Noble UI components whose purpose is to interact with and feed the hidden, native rendering engine of the .NET framework.

The Code in Action

Here is a streamlined look at how a standard CRUD ViewModel expresses its semantic role through attributes and clean design:

using System.Collections.ObjectModel;
using System.ComponentModel;
using System.Windows.Input;
using Clprolf.ArchUnitNet.Attributes;

namespace Clprolf.Example.WPF.Mvvm.Impl
{
    [ClAgent] // Marked as a Presentation Agent
    public class UserViewModel : IUserViewModel
    {
        public event PropertyChangedEventHandler? PropertyChanged;

        // ObservableCollection handles UI notification for list updates
        public ObservableCollection<User> Users { get; set; } = new();

        private User? _selectedUser;
        public User? SelectedUser
        {
            get => _selectedUser;
            set
            {
                if (_selectedUser != value)
                {
                    _selectedUser = value;
                    OnPropertyChanged(nameof(SelectedUser));
                    if (_selectedUser != null) NewUserName = _selectedUser.Name;
                }
            }
        }

        private string _newUserName = string.Empty;
        public string NewUserName
        {
            get => _newUserName;
            set
            {
                if (_newUserName != value)
                {
                    _newUserName = value;
                    OnPropertyChanged(nameof(NewUserName));
                }
            }
        }

        // Intention Agents (CRUD Commands)
        public ICommand AddCommand { get; }

        public UserViewModel()
        {
            AddCommand = new RelayCommand(ExecuteAdd, CanExecuteAdd);

            // Initial data seeding
            // (In a full production setup, this would be fetched from a Repository Worker)
            Users.Add(new User("Alice"));
            Users.Add(new User("Bob"));
        }

        public void ExecuteAdd(object? parameter)
        {
            Users.Add(new User(NewUserName));
            NewUserName = string.Empty; 
            // Save to repository worker here...
        }

        public bool CanExecuteAdd(object? parameter) => !string.IsNullOrWhiteSpace(NewUserName);

        private void OnPropertyChanged(string propertyName)
        {
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
        }
    }
}

The Architecture Blueprint

To see how this language structures a real application, here is the exact layout of the WPF project. Notice how the namespaces map directly to our semantic roles rather than generic UI folders:

Clprolf.Example.WPF/
│
├── App.xaml.cs                     --> [ClWorker] (Application Bootstrapper)
│
├── Entities/
│   └── User.cs                     --> [ClAgent] (Domain Identity)
│
├── Mvvm/
│   ├── IUserViewModel.cs           --> [ClFamily] [ClAgent] (Contract)
│   └── Impl/
│       └── UserViewModel.cs        --> [ClAgent] (Presentation Ambassador)
│
└── Agents/
    └── Impl/
        └── SystemOriented/
            ├── UserWindow.xaml.cs  --> [ClSystem] (UI Component)
            ├── RelayCommand.cs     --> [ClSystem] (Intention Driver)

    └── Traits/
        └── IClNotifyPropertyChanged.cs --> [ClTrait][ClAgent]

As you can see, every single component—from the window to the command framework—has been assigned a strict semantic responsibility.

Wiring the Ecosystem Together

To understand how these Agents interact, look at how the application starts.

First, we have our UserWindow, a System-Oriented Agent designed to serve the native WPF rendering engine by hosting the visual tree and binding the context:

[ClSystem]
public partial class UserWindow : Window
{
    public UserWindow(UserViewModel vm)
    {
        InitializeComponent();
        DataContext = vm;
    }
}

Then, we have the App.xaml.cs. This is not an Agent; it has no business intent. It is a Clprolf Worker—an automated executor whose only job is to assemble the pieces, inject the dependencies, and start the factory:

[ClWorker]
public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);

        var vm = new UserViewModel();
        var userWin = new UserWindow(vm);

        userWin.Show(); // The worker hands over control to the System Agents
    }
}

Guarding the Architecture with ArchUnitNET

To ensure these semantic boundaries are never violated during development, we use automated architecture tests. For instance, we can write a rule ensuring that any interface marked as a Trait (a reusable structural behavior) only extends other Traits or external system interfaces, preventing illegal coupling with hard Agents.

Here is the condition that enforces this:


[ClAgent]
internal sealed class TraitInterfacesMustExtendOnlyTraitInterfacesCondition : ICondition<Interface>
{
    public string Description => "extend only trait interfaces";

    public IEnumerable<ConditionResult> Check(IEnumerable<Interface> objects, Architecture architecture)
    {
        foreach (var interf in objects)
        {
            if (!interf.IsTrait()) { yield return new ConditionResult(interf, true, $"{interf.FullName} is ignored (Not a [ClTrait] interface)"); continue; }
            if (interf.ImplementedInterfaces.IsNullOrEmpty()) { yield return new ConditionResult(interf, true, $"{interf.FullName} has no parent interface"); continue; }

            bool allParentsAreTraitsOrExternal = interf.ImplementedInterfaces.All(parent => 
                interf.HasInterfaceBypass() || parent.IsTrait() || !parent.IsClprolf()
            );

            var faultyParent = interf.ImplementedInterfaces.FirstOrDefault(parent => 
                !interf.HasInterfaceBypass() && !parent.IsTrait() && parent.IsClprolf()
            );

            yield return new ConditionResult(
                interf, 
                allParentsAreTraitsOrExternal,
                allParentsAreTraitsOrExternal 
                    ? $"All parent interfaces of {interf.FullName} are traits or external third-party interfaces."
                    : $"{interf.FullName} is a trait interface but it inherits from {faultyParent?.FullName} which is NEITHER a trait interface NOR an external system interface"
            );
        }
    }

    public bool CheckEmpty() => true;
}

Conclusion

By mapping the technical structure of MVVM into a simple, unified vocabulary of Agents and Workers, the cognitive load drops. The architecture stops being just about "WPF mechanics" and becomes a clear map of responsibilities.

The main benefit of this approach is consistency: whether you are looking at a desktop view-model, a web API controller, or a console application, the semantic definitions remain the same.

Securing Your Spring Boot Architecture: A Pragmatic Approach with Clprolf

Charles Koffler — Thu, 11 Jun 2026 12:39:31 +0000

Introduction

Spring Boot is an incredible framework. It gives developers immense freedom to build and scale applications quickly. However, in large teams or complex environments, this absolute freedom can sometimes lead to architectural drift. Spring cares about making your application work, but it doesn't enforce code symmetry or strict layering.

How can we ensure our architecture remains clean, maintainable, and predictable over time?

In this article, we'll share a real-world example of how we achieved psychological safety for our development team by pairing Spring Boot with Clprolf, a lightweight semantic framework designed to enforce architectural rules through automated tests.

The Core Concept: Architectural Psychological Safety

When a project grows, the mental load on tech leads and developers increases. You worry about whether a junior developer accidentally bypassed a service layer, or if a database entity is leaking into a controller.

Instead of relying solely on code reviews, we can use a declarative approach. By using semantic annotations, we tell our framework what a class is supposed to be, and automated tests verify that the rules are never broken.

A Practical Example: The Weather Observation API

Let’s look at a concrete implementation: a clean, batch-optimized Weather API. We organized our components using Clprolf's core concepts: @ClAgent (for functional components), @ClFamily (for contracts/interfaces), and @ClWorker (for specialized execution units).

1. The Pure Contract (Interface)

Our controller interface is completely decoupled from the Web framework. It expresses pure business intent and is tagged as a framework family contract.

package org.clprolf.weatherapp.controllers;

import org.clprolf.framework.ClAgent;
import org.clprolf.framework.ClFamily;
import org.clprolf.weatherapp.entities.Observation;
import org.springframework.http.ResponseEntity;
import java.util.List;

@ClAgent
@ClFamily
public interface ClprolfWeatherController {
    ResponseEntity<List<Observation>> getObsByStation(String station);
    ResponseEntity<Observation> createObservation(Observation observation);
    ResponseEntity<List<Observation>> getAllObs();
}

2. The Spring Boot Implementation

The implementation handles the HTTP plumbing. Notice how clean it remains, focusing only on routing and database interaction via the repository (ObservationDao).

package org.clprolf.weatherapp.controllers.impl;

import jakarta.validation.Valid;
import org.clprolf.framework.ClAgent;
import org.clprolf.weatherapp.controllers.ClprolfWeatherController;
import org.clprolf.weatherapp.entities.Observation;
import org.clprolf.weatherapp.repos.ObservationDao;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@ClAgent
@RestController
@RequestMapping("/weatherapi/observations")
public class ClprolfWeatherControllerImpl implements ClprolfWeatherController {

    @Autowired
    private ObservationDao obsDao;

    @GetMapping("get/station/{station}")
    public ResponseEntity<List<Observation>> getObsByStation(@PathVariable String station) {
        List<Observation> observations = obsDao.findByIdStation(station);
        return observations.isEmpty() ? ResponseEntity.notFound().build() : ResponseEntity.ok(observations);
    }

    @PostMapping("create")
    @Override
    public ResponseEntity<Observation> createObservation(@Valid @RequestBody Observation observation) {
        Observation savedObservation = obsDao.save(observation);
        return ResponseEntity.status(HttpStatus.CREATED).body(savedObservation);
    }

    @GetMapping("all")
    @Override
    public ResponseEntity<List<Observation>> getAllObs() {
        List<Observation> allObservations = obsDao.findAll();
        return allObservations.isEmpty() ? ResponseEntity.noContent().build() : ResponseEntity.ok(allObservations);
    }
}

💡 A Note on the Service Layer & Clprolf

For brevity, this CRUD example connects the Controller directly to the Worker (DAO). In a real-world application, you would naturally introduce a Service layer to handle specific business rules.

In the Clprolf ecosystem, this Service would simply be another @ClAgent. It is the core Domain Agent executing its specific functional job, sitting between the API entrypoint (the Controller) and the infrastructure worker (the DAO).

3. The Data Access Layer & Composite Identity

To keep our database layer optimized for high-volume weather data, we separated the identity from the entity. Here is our immutable composite ID (ObservationId) and its corresponding data access object (ObservationDao).

Notice how Clprolf's annotations (@ClAgent, @ClWorker) live alongside standard JPA annotations, cleanly documenting the role of each class.

package org.clprolf.weatherapp.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Embeddable;
import org.clprolf.framework.ClAgent;
import java.time.OffsetDateTime;
import java.util.Objects;

@ClAgent
@Embeddable
public class ObservationId {

    @Column(length = 8)
    private String station;
    private OffsetDateTime dayUTC; // Leveraging Java 8+ time types for strict UTC handling

    public String getStation() { return station; }
    public OffsetDateTime getDayUTC() { return dayUTC; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        ObservationId that = (ObservationId) o;
        return Objects.equals(station, that.station) && Objects.equals(dayUTC, that.dayUTC);
    }

    @Override
    public int hashCode() {
        return Objects.hash(station, dayUTC);
    }
}

And the Data Access Object (DAO) interface, tagged as a framework worker component:

package org.clprolf.weatherapp.repos;

import java.util.List;
import org.clprolf.framework.ClFamily;
import org.clprolf.framework.ClWorker;
import org.clprolf.weatherapp.entities.Observation;
import org.clprolf.weatherapp.entities.ObservationId;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@ClWorker
@ClFamily
@Repository
public interface ObservationDao extends JpaRepository<Observation, ObservationId> {
    List<Observation> findByIdStation(String station);
}

Automated Enforcement in the CI/CD Pipeline

The real magic happens behind the scenes. We use ArchUnit rules integrated into our test suite to ensure that no one violates the design patterns.

For instance, we enforce that specific trait interfaces extend only other trait interfaces. If a rule cannot be evaluated yet (e.g., if a project doesn't use traits on day one), we safely allow it to bypass without breaking the CI build using .allowEmptyShould(true).

Here is a glimpse of how strict structural checks are written:

@ArchTest
static final ArchRule trait_interfaces_must_extend_only_trait_interfaces =
        classes()
                .that().areInterfaces()
                .and().areAnnotatedWith(ClTrait.class)
                .should(new ArchCondition<JavaClass>("extend only @ClTrait") {
                    @Override
                    public void check(JavaClass trait, ConditionEvents events) {
                        for (JavaClass parent : trait.getRawInterfaces()) {
                            boolean ok = parent.isAnnotatedWith(ClTrait.class)
                                      || parent.isAnnotatedWith(ClFree.class)
                                      || (!parent.isAnnotatedWith(ClFamily.class) && !parent.isAnnotatedWith(ClTrait.class));

                            events.add(new SimpleConditionEvent(trait, ok, trait.getName() + " extends " + parent.getName()));
                        }
                    }
                })
                .allowEmptyShould(true); // Prevents blocking the CI pipeline prematurely

Conclusion

By combining the runtime power of Spring Boot with the architectural guardrails of Clprolf, we created a safe environment for our team. Senior developers can rest assured that the design pattern is respected, and junior developers receive immediate, automated feedback on their code structure before it even reaches a human code review.

It’s not about restricting creativity; it’s about removing the anxiety of architectural erosion.

Introducing the ArchUnit Checker for the Clprolf Framework

Charles Koffler — Mon, 01 Jun 2026 07:34:53 +0000

One of the most interesting aspects of architectural frameworks is not the rules themselves, but the ability to verify that those rules are actually being followed.

The Clprolf Framework now includes automated checker extensions for both Java and .NET (C#) projects. Rather than relying solely on documentation, Clprolf's structural principles can be validated automatically during development and continuous integration.

What is Clprolf?

Clprolf ("Clear PROgramming Language and Framework") is a lightweight object-oriented framework built around a simple idea:

A class should clearly express its primary role.

To make this explicit, Clprolf distinguishes between business-oriented classes and technical classes.

Classes        Interfaces
--------        ----------
Agent           Family
Worker          Trait
Draft           Free

The framework is based on two fundamental principles:

Separate business concerns (Agents) from technical concerns (Workers).
Preserve the conceptual domain through inheritance.

Bringing Architecture into the Build Process

Architectural guidelines are often written down, discussed, and eventually forgotten. The Clprolf checker takes a different approach: architectural rules become executable tests.

By using ArchUnit in Java and ArchUnitNET in C# .NET, violations can be detected automatically from your favorite IDE (IntelliJ IDEA, Visual Studio), build tools (Maven, dotnet CLI), or any CI/CD pipeline.

Ecosystem Symmetry (.NET vs Java)

The framework maintains absolute functional parity between ecosystems. The syntax effortlessly mirrors each language's native style:

In Java (ArchUnit): Marked using @Annotation syntax.
In .NET (ArchUnitNET): Marked using native C# [Attribute] syntax enclosed in brackets.

Core Rules

The checker validates the framework's core rules through 8 mandatory semantic tests (ClprolfArchTest in Java, or its xUnit equivalent in .NET).

In this section:
To keep the documentation simple, the optional ClSystem annotation is not included in the rules' descriptions. It is seamlessly handled by the checker as an independent role.

1. A class cannot mix roles (`clprolf_classes_must_not_mix_agent_and_worker`)

A class cannot be annotated as both Agent and Worker.

// Java
@ClAgent @ClWorker
public class InvalidClass { }

// C#
[ClAgent, ClWorker]
public class InvalidClass { }

A class must have a single primary responsibility.

2. Inheritance must not mix domains (`agent_worker_inheritance_must_not_mix`)

A Worker class cannot inherit from an Agent class, and vice versa. This ensures that inheritance strictly preserves the conceptual domain. Forcing an override is possible locally using @ClBypass (or [ClBypass]).

3. Family interfaces must match implementation roles (`family_role_must_match_implementation`)

A class implementing a @ClFamily (or [ClFamily]) interface must have a role compatible with the target role of that interface. For example, an Agent family interface must be implemented by an Agent class.

4. Trait interfaces must extend only trait interfaces (`trait_interfaces_must_extend_only_trait_interfaces`)

A @ClTrait interface can only inherit from other @ClTrait interfaces. A trait remains a trait throughout the contract hierarchy.

5. Clprolf interfaces must declare a target role (`clprolf_interfaces_must_have_target_role`)

Every Family and Trait interface must explicitly declare its target domain:

A Family interface must declare exactly one target role: Agent or Worker.
A Trait interface must declare at least one target role (Agent, Worker, or exceptionally both for cross-cutting capabilities).

6. Inheriting interface roles must match trait target roles (`inheriting_interface_role_must_match_trait_interface_target_role`)

When an interface (Family or Trait) inherits from a Trait, its target role must be compatible with that trait. Cross-cutting traits (annotated as both Agent and Worker) are universally compatible.

7. Family target roles must match inherited family interfaces (`family_interface_target_role_must_match_inherited_family_interface`)

When a Family interface inherits from another Family interface, both must share compatible target roles to preserve the conceptual domain across contract hierarchies.

8. Direct trait implementation must respect trait roles (`trait_interface_role_must_match_direct_implementation`)

While direct implementation of a Trait by a concrete class is tolerated in standard mode, the class role must match the trait's target role.

// Valid: Payable is an Agent trait
@ClAgent
public class Order implements Payable { }

Optional Strict Validation

A second test suite, ClprolfStrictArchTest (available in both GitHub repositories), adds 4 strict rules for teams demanding absolute classification. These can also be run standalone to audit technical debt on existing legacy codebases.

Every class must declare a role (optional_all_classes_should_have_clprolf_role): All classes must explicitly be tagged as Agent, Worker, or Draft.
Every interface must declare a role (optional_all_interfaces_should_have_clprolf_role): All interfaces must explicitly be tagged as Family, Trait, or Free.
No direct trait implementation (optional_class_should_not_implement_trait_directly): Classes are forbidden from implementing a Trait directly; traits must be inherited through a Family interface.
Single Family interface implementation (optional_class_must_implement_only_one_family_interface): A class can only implement one primary Family interface, effectively mimicking single inheritance patterns. Multiple inheritance is cleanly shifted into the Family interface itself:

// C# Strict Pattern
[ClAgent, ClFamily]
public interface IHorse : IAnimal, IMammal, IPayable { }

[ClAgent]
public class Horse : IHorse { }

Explicit Escapes: Granular Bypasses

Clprolf values pragmatism over dogmatism. When edge cases occur (such as integrating legacy code or external libraries), developers can explicitly sign off on architectural exceptions using precise, language-native operators:

@ClBypass / `[ClBypass]`: Overrides role mismatches between Agent and Worker domains.
@ClInterfaceBypass / `[ClInterfaceBypass]`: Overrides structural interface constraints (e.g., forcing multiple family implementations or uncommon interface inheritances).

The checkers are highly intelligent: utilizing a bypass does not blind the parser. It merely allows that specific exception while continuing to recursively validate the rest of the inheritance chain.

Why It Matters

Many frameworks provide architectural recommendations that eventually become shelfware.

Clprolf goes one step further by making those recommendations automatically verifiable across the industry's two most prominent enterprise ecosystems. Whether your infrastructure runs on Spring Boot, .NET Core, or a microservice mix of both, Clprolf provides an identical, lightweight, and executable guardrail to help teams maintain structural consistency as codebases evolve.

Clprolf — Official Documentation

Charles Koffler — Mon, 25 May 2026 16:47:03 +0000

Introduction

Clprolf ("Clear PROgramming Language and Framework") is a homegrown architectural framework, for Java and C# .NET. Its motto is "Don't use it - You don't need it!".

Its goal is to make certain object-oriented programming best practices explicit, without introducing heavy architecture or a steep learning curve.
Thus, the framework helps adhere to the well-known SOLID principles.

Clprolf is based on a simple idea:

A class should clearly express its primary role.

The framework helps to:

separate business logic from technical code,
limit architectural drift,
make inheritance more coherent,
improve system readability.

In Java (ArchUnit)

In the Java ecosystem, components are marked using annotations:

import org.clprolf.framework.ClAgent;

@ClAgent
public class CarImpl implements Car {
    // Agent logic...
}

In C# (ArchUnitNET)

In the .NET ecosystem, the strict equivalent uses C# Attributes enclosed in brackets [...] placed directly above the class:

using Clprolf.ArchUnitNet.Attributes;

namespace MyApp.Agents {

    [ClAgent]
    public class Car : ICar
    {
        // Agent logic...
    }

}

💡 Note for Framework Users (.NET vs Java)

Syntax: Java's @Annotation becomes [Attribute] in C#.

I) The Two Fundamental Principles

Clprolf is built around two central principles.

1. A class is either business/conceptual or technical

Every class belongs to one of the following worlds:

Business / Domain World

The class represents a business or conceptual responsibility.

Examples:

order management,
business logic,
simulation,
functional orchestration,
but also system-oriented agents.

These classes are declared using:

@ClAgent

Technical World

The class performs a technical task executed by the system:

database access (via system agents),
networking (often by utilizing low-level agents),
file handling (most frequently with system-oriented agents),
display / rendering,
infrastructure,
no conceptual domain; it is just the system executing technical agents or starting an application,
generally a system technical service associated with an agent.

These classes are declared using:

@ClWorker

2. Inheritance must preserve the domain

A class should only inherit from another class belonging to the same conceptual domain.

Otherwise:

composition should be used.

This principle prevents incoherent hierarchies and mixed responsibilities.

II) Progressive Adoption and Customization

The framework offers total flexibility in both its deployment strategy and its terminology.

II.1) Step-by-Step Adoption

Integrating Clprolf into a project can be done incrementally. There is no need to enforce every rule from day one.

Step 1: Classes First. You can focus exclusively on the core separation between @ClAgent (or ClSystem) and @ClWorker. This allows the team to master the class splitting without initial friction.
Step 2: Interfaces Later (Optional). The interface model (ClFamily, ClTrait) can be introduced at a later stage.

If you find the Clprolf interface system too disruptive compared to your habits or traditional OOP practices, you can choose to ignore it entirely. The framework remains fully functional and highly effective just for your classes.

II.2) Tailoring the Terminology

If the default vocabulary of Clprolf does not fit your team's nomenclature, the framework is completely agnostic regarding name choices. Since the ArchUnit checker targets the actual declaration types, a simple automated refactoring (Rename) in your IDE is all it takes to adapt the framework to your company's culture.

Here are a few examples of alternative naming conventions:

Default Role	Conceptual Alternative	Technical Alternative
`@ClAgent`	`@ClConcept`	`@ClDomain`
`@ClWorker`	`@ClMechanism`	`@ClInfrastructure`
`@ClSystem`	`@ClBridge`	`@ClLowLevel`

III) Class Types

Clprolf contains only three class types.

III.1) `ClAgent`

Represents a business or conceptual class.

An agent:

contains business or conceptual logic,
orchestrates processes,
makes decisions,
avoids heavy technical code, which is often delegated to an associated worker,
can be system-oriented, such as Connection or Socket (in which case ClSystem can also be used).

Example:

@ClAgent
public class OrderProcessor {

    private OrderRepository repository;

    public void process(Order order) {
        if(order.total() <= 0) {
            throw new Error();
        }
        repository.save(order);
    }
}

Note: Entities are considered agents because they possess a domain, even without methods.

III.2) `ClWorker`

Represents a system service.

A worker class is primarily intended to support agent classes rather than be organized around a class domain.

Workers provide technical and infrastructure services. They may coordinate or use low-level agents (system agents) such as File, Connection, Random, Logger, or Parser, but unlike those classes, a worker is not organized around a class domain of its own.

Instead, it exists to support other components through technical mechanisms, infrastructure access, application startup, operating-system interaction, or similar responsibilities.

A worker:

Is a system service;
Provides technical support;
Manages infrastructure and execution mechanisms;
Contains technical code;
Uses system abstractions, but is not one itself;
Is often there to assist an agent class (including system agents) with rendering/display, direct database access, etc.;
Allows for the separation of domain/functional code from purely technical code.

III.3) The Optional `ClSystem` Role

The @ClSystem annotation (or [ClSystem] attribute in C#) can be used for system-oriented agents. However, it is not mandatory, keeping the framework as simple as possible.
If used, mixing inheritance between standard agents and system-oriented agents is strictly forbidden. The checker will then treat them as a completely independent role.
Developers who prefer to explicitly declare and finely control system-oriented agents (such as File) can annotate them as ClSystem instead of ClAgent.
Note that classes imposed by third-party frameworks—such as Controllers, Routing, or Middlewares (Filters/Interceptors in Java)—can also be considered ClSystem classes.
ClSystem provides a more technical perspective for those who prefer not to view system-oriented agents as pure agents, allowing them to be separated from more traditional agents.

III.4) `ClDraft`

An object without a defined role. Normally, it shouldn't be essential.

Used:

during prototyping,
during refactoring,
when the role is not yet clear.

Example:

@ClDraft
public class TemporaryManager {
}

ClDraft enables a flexible approach similar to classical OOP.

III.5) Primary Domain and Technical Code

Clprolf encourages moving as much technical code as possible from agent classes into worker classes.

However, an agent may contain a reasonable amount of technical code when doing so improves simplicity or readability.

An agent always has a primary domain representing its central responsibility.

Secondary responsibilities may exist as long as they remain consistent with that primary domain.

III.6) An "Opinionated" Framework for the Agent/Worker Choice

Some responsibilities can be interpreted in different ways depending on the architectural vision adopted.

For example, a connection can be represented:

as an agent (or ClSystem), if viewed as a functional abstraction;
or as a worker, if considered a purely technical mechanism.

However, in such cases, the Clprolf framework imposes the use of an agent. For example, for a Connection class:

an agent to represent the connection (though you can also choose ClSystem),
and delegate the technical code to one or more worker classes.

This is why Clprolf can be described as an "opinionated" framework.
As soon as a domain can be identified, it must be chosen over the worker perspective. This choice is argued by the fact that agents and abstractions are easier to manipulate and facilitate design.
However, declaring the Connection class as a ClAgent (or ClSystem) does not preclude it from having a worker for its own technical needs.

Java Example Confirming the Clprolf Vision: `java.io.File`

The recent OpenJDK implementation of java.io.File reveals a fairly long class of about 2,000 lines. The class delegates all purely technical, non-domain-related work to an attribute that acts as the strict equivalent of a worker (FileSystem).

private static final FileSystem FS = DefaultFileSystem.getFileSystem();

 public boolean delete() {
        if (isInvalid()) {
            return false;
        }
        return FS.delete(this);
    }

       CLPROLF CONCEPT                        JAVA SOURCE CODE (OpenJDK)
┌──────────────────────────┐            ┌──────────────────────────┐
│ @ClAgent (@ClSystem)     │             │       java.io.File       │
│      (System Agent)      │            │                          │
│ Represents the concept   │            │ Manages the file         │
│ of a file and its path.  │            │ abstraction and status.  │
│ Conceptual methods       │            │ Conceptual methods       │
└────────────┬─────────────┘            └────────────┬─────────────┘
             │                                       │
             │ delegates to                          │ calls
             ▼                                       ▼
┌──────────────────────────┐            ┌──────────────────────────┐
│        @ClWorker         │            │    java.io.FileSystem    │
│    (Low-Level Worker)    │            │       (FS variable)      │
│ Performs OS-specific     │            │ OS-specific implement.   │
│ validation and access.   │            │ (WinNT/UnixFileSystem).  │
└──────────────────────────┘            └──────────────────────────┘

Note: java.io.UnixFileSystem and WinNTFileSystem contain many native methods.

IV) Inheritance

Class inheritance can be forced using @ClBypass above the class, but this should be rare.

Valid Example

@ClAgent
public class Animal {
}

@ClAgent
public class Dog extends Animal {
}

Discouraged Example

@ClWorker
public class ClientRepository {
}

@ClAgent
public class Dog extends ClientRepository {
}

Here, the domains are incompatible.

Composition should be used instead.

Inheritance can be forced using @ClBypass above the class.

V) Flexibility

Clprolf is flexible.

The developer therefore keeps their freedom:

mixing responsibilities when necessary,
progressive migration,
compatibility with existing code,
while always maintaining a primary domain.

The framework mainly acts as:

a structural guide.

VI) Interfaces

In Clprolf, interfaces are viewed as:

abstract forms of inheritance.

They therefore participate in the structural continuity of the system.

ClFamily = primary family interface
ClTrait  = trait, shared capability between families
ClDraft = unrestricted interface

In Clprolf, interfaces are not viewed as simple technical contracts.

Both extends and implements relationships are considered genuine conceptual inheritance relationships.

VI.1) `ClFamily`

An interface representing an abstract family.

Used for:

polymorphism,
decoupling,
implementation variants.

Family interfaces also have a target role:

ClAgent
or ClWorker

Example

@ClAgent
@ClFamily
public interface Animal {

    void eat(int quantity);

}

The hierarchy of ClFamily interfaces naturally reflects the hierarchy of concrete classes.

@ClAgent
@ClFamily
public interface Horse extends Animal {

    void jump(int height);

}

Which may lead to:

@ClAgent
public class AnimalImpl implements Animal { (...) }

@ClAgent
public class HorseImpl extends AnimalImpl implements Horse { (...) }

VI.2) `ClTrait`

An interface representing a shared capability across multiple ClFamily.

Traits also use a target role:

ClAgent
ClWorker

Note: a @ClTrait may be annotated with both @ClAgent and @ClWorker.

This exception is reserved for genuinely cross-cutting traits that can be used by both agents and workers.

Business Example

@ClAgent
@ClTrait
public interface Payable {
    void pay();
}

Technical Example

@ClWorker
@ClTrait
public interface Persistable {
    void save();
}

VI.3) Illustration of the Interface Family / Implementation Parallel

[ABSTRACT WORLD / INTERFACES]          │    [CONCRETE WORLD / CLASSES]
                                       │
       @ClAgent @ClFamily              │        @ClAgent
        interface Animal               │       class AnimalImpl
               ▲                       │               ▲
               │ (extends)             │               │ (extends)
               │                       │               │
       @ClAgent @ClFamily              │        @ClAgent
         interface Horse               │       class HorseImpl
               ▲                       │               ▼ (implements)
               │                       │       👉 implements Horse
               └───────────────────────┼───────  (and extends AnimalImpl)
                (Structural Inheritance)│
                                       │
 ──────────────────────────────────────┴─────────────────────────────────
  👉 THE TRAIT (Cross-cutting):

       @ClAgent @ClTrait               │
        interface Jumpable             │
               ▲                       │
               │ (inherited by Family) │
               │                       │
     Horse extends Jumpable            │

VI.4) `ClFree`

A generic interface without a specific role. It shouldn't be necessary.

Allows flexibility.

Example

@ClFree
public interface ExternalApi {
}

VI.5) Using Interfaces

In Clprolf, Family interfaces closely resemble pure abstract classes.

They are intended to be implemented by one or more future Clprolf classes. Therefore, they have a target role (agent or worker).

A class can only implement a single main Family at a time, and the class role must match the target role of the interface. Clprolf thus uses single implementation for interfaces, in the same way that Java uses single inheritance for classes. Indeed, a Family is always the structural reflection of its implementation. This notably allows for systematic loose coupling.
However, multiple implementation is not removed, but rather shifted to the Family implemented by the class.
This might seem restrictive and unconventional, but it only applies in strict mode, which is not the default. This prevents multiple implementations of the same family from repeating a multi-contract declaration, and helps developers quickly understand what the classes actually implement.

Trait interfaces express a common functionality across multiple Family interfaces.

A Trait therefore represents a cross-cutting trait shared among several families.

Normally, a Trait can only be inherited by a Family interface, and not directly implemented by a class. This prevents a trait from being separated from its family interface, and clarifies class implementations (especially when a family has multiple implementations).

However, this only applies in strict mode, which is not the default.

Concrete class
    ↓ implements
ClFamily
    ↓ inherits from
ClTrait

Note: A Family interface can inherit from multiple Family or Trait interfaces.
A Trait interface can only inherit from other Traits, because a trait remains a trait.

Interface inheritance can still be forced using @ClInterfaceBypass above the interface (or @ClBypass to force inheritance between different target roles). However, these bypasses should be rare.

VI.6) A Real-World Example of `ClFamily` and `ClTrait` Interfaces

Let's look at this real-world example, which utilizes a design perfectly applicable to the Clprolf Framework:

package com.tngtech.archunit.lang;

@ClAgent @ClFamily
public interface ArchRule extends CanBeEvaluated, CanOverrideDescription<ArchRule> {
//(…)
}

package com.tngtech.archunit.library;

public final class Architectures {
//(…)
@ClAgent
public static final class LayeredArchitecture implements ArchRule {
// (…)
}

}

In this example, CanBeEvaluated and CanOverrideDescription act as @ClTrait interfaces, while ArchRule formalizes the @ClFamily.

VI.7) Note on Clprolf and the Interface Segregation Principle (ISP)

Clprolf inherently respects the ISP; it is simply a matter of adapting the design of your classes and interfaces using the appropriate families and traits:

@ClAgent
@ClTrait
public interface Scanner {
    void scan(Document doc);
}

@ClAgent
@ClTrait
public interface Fax {
    void fax(Document doc);
}

@ClAgent
@ClTrait
public interface Printer {
    void print(Document doc);
}

@ClAgent
@ClFamily
public interface OldPrinter extends Printer {

}

@ClAgent
@ClFamily
public interface ModernPrinter extends OldPrinter, Scanner, Fax {
}

@ClAgent
public class OldPrinterImpl implements OldPrinter {
    // (...)
}

@ClAgent
public class ModernPrinterImpl implements ModernPrinter {
    // (...)
}

VII) General Architecture

Clprolf naturally encourages a simple architecture.

agent
    ↓ delegates to
worker

agent classes contain:

business rules,
decisions,
orchestration.

worker classes perform:

technical work,
system access,
machine operations.

An agent delegates technical code to one or more worker classes.

A worker serves the agent.

┌────────────────────────────────────────────────────┐
│                       AGENT                        │
│       conceptual behavior, domain responsibility   │
│                                                    │
└─────────────────────────┬──────────────────────────┘
                          │
                          │ uses / delegates to
                          ▼
┌────────────────────────────────────────────────────┐
│                       WORKER                       │
│          system service for technical execution      │
│               serving an agent                     │
└─────────────────────────┬──────────────────────────┘
                          │
                          │ may use
                          ▼
┌────────────────────────────────────────────────────┐
│              (SYSTEM-ORIENTED) AGENT (ClSystem)    │
│   conceptual object connected to system behavior   │
│   examples: stream, socket, thread, file, window   │
└─────────────────────────┬──────────────────────────┘
                          │
                          │ delegates low-level work to
                          ▼
┌────────────────────────────────────────────────────┐
│                    (LOW-LEVEL) WORKER              │
│     native call, rendering, I/O, OS/runtime work   │
└────────────────────────────────────────────────────┘

VIII) Purpose of the framework

Clprolf does not aim to replace classical OOP.

It aims to make certain important distinctions explicit:

business vs technical,
coherent inheritance vs composition,
primary responsibility of a class.

IX) ArchUnit Checker

An ArchUnit-based checker is available for the Clprolf Framework on GitHub. It is open-source and consists of two classes: ClprolfArchTest and ClprolfStrictArchTest. It validates semantic rules.
The rules in ClprolfStrictArchTest are optional. Likewise, it is easy to change the annotation names if you prefer a different vocabulary.

1. Java Version (ArchUnit)

Available on GitHub, the Java checker is open-source and centers around two main test classes:

ClprolfArchTest: Validates the standard and fundamental semantic rules of the framework.
ClprolfStrictArchTest: Gathers optional, more rigid constraints for demanding projects (such as forbidding a class from directly implementing a ClTrait). The checkers (both Java and .NET) also contain the definitions for Clprolf annotations (or attributes).

In this section:
To keep the documentation simple, the optional ClSystem annotation is not included in the rules' descriptions. It is seamlessly handled by the checker as an independent role.

2. C# .NET Version (ArchUnitNET)

The port of the .NET extension is available and published on GitHub.

The Visual Studio solution (2022 to date) contains a project with the framework and ArchUnit rules, along with an xUnit project for the tests.
A third example project is also included. There are currently 8 mandatory tests and 4 strict tests.

Rules to Follow

clprolf_classes_must_not_mix_agent_and_worker:

A class cannot be annotated as both @ClAgent and @ClWorker.

agent_worker_inheritance_must_not_mix

A @ClWorker class cannot inherit from a @ClAgent class, and vice versa.

family_role_must_match_implementation

The target role of a @ClFamily interface must match the role of the implementing class (@ClAgent or @ClWorker). Bypassing is possible using @ClBypass.

(non-strict mode) trait_interface_role_must_match_direct_implementation

A class that directly implements a trait must have a compatible role (unless bypassed with @ClBypass). Forbidden in strict mode.

trait_interfaces_must_extend_only_trait_interfaces

@ClTrait interfaces can only inherit from other @ClTrait interfaces. Bypassing is possible using @ClInterfaceBypass.

clprolf_interfaces_must_have_target_role

@ClFamily interfaces must have exactly one target role: @ClAgent or @ClWorker.
@ClTrait interfaces must have at least one target role: @ClAgent, @ClWorker, or exceptionally both.

inheriting_interface_role_must_match_trait_interface_target_role

Interfaces (family or trait) that inherit from a trait must have a role compatible with that trait (unless bypassed with @ClBypass).

family_interface_target_role_must_match_inherited_family_interface

Family interfaces inherited by another family interface must have a compatible role, unless @ClBypass is used.

Stricter Rules:

optional_all_classes_should_have_clprolf_role

All classes must have a Clprolf role (@ClAgent, @ClWorker, or @ClDraft).

optional_all_interfaces_should_have_clprolf_role

All interfaces must have a Clprolf role (@ClFamily, @ClTrait, or @ClFree).

optional_class_should_not_implement_trait_directly

A class cannot directly implement a @ClTrait interface (unless @ClInterfaceBypass is used).

optional_class_must_implement_only_one_family_interface (OPTIONAL)

A Clprolf class can only implement a single @ClFamily interface. Bypassing is possible using @ClInterfaceBypass.

X) Clprolf and the SOLID Principles

S — Single Responsibility Principle (SRP)

The framework naturally helps apply the Single Responsibility Principle (SRP). Indeed, each class possesses its own conceptual or business domain, which is strictly preserved during inheritance. Adhering strictly to Clprolf makes achieving this even easier.

O — Open-Closed Principle (OCP)

This principle encourages us to anticipate future evolutions as extensions rather than code corrections. The Clprolf framework facilitates extensions through the strict separation of conceptual domains and workers. ClFamily interfaces promote clear visibility of the interfaces used within classes and push for well-thought-out features. ClTrait interfaces allow us to keep ClFamily interfaces even simpler and purer, while enabling traits to be shared and reused seamlessly.

L — Liskov Substitution Principle (LSP)

Clprolf enforces inheritance that remains strictly within the same conceptual domain, alongside the separation between ClAgent and ClWorker. Thus, Liskov's LSP principle is more easily taken into account, as a Square class does not share the same conceptual domain as a Rectangle.
Indeed, a Giraffe class belongs to the same domain as an Animal, from which it inherits its natural behaviors. Conversely, a Square class does not share the true nature of a Rectangle (it cannot have independent length and width). In Clprolf, they therefore do not belong to the same conceptual domain, which prevents abusive inheritance and avoids LSP violations.

I — Interface Segregation Principle (ISP)

This principle states that a client should not be forced to implement methods it does not use. With Clprolf, interfaces are custom-tailored for the client, and traits are highly precise. Furthermore, inheritance between interfaces is strictly controlled, thereby promoting compliance with the ISP.

D — Dependency Injection (DI)

Dependency injection implies loose coupling with implementations. This loose coupling is encouraged and facilitated by ClFamily interfaces, which are intimately bound to their respective classes.

"Favoring Composition over Inheritance"

The Clprolf framework ensures that inheritance is used sparingly and with precision, while relying on composition for everything else. It offers a practical and intuitive way to choose between the two.

XI) Clprolf and Existing Architectures

Clprolf is compatible with existing architectural approaches such as Domain-Driven Design (DDD), Model-View-Controller (MVC), Clean Architecture, Hexagonal Architecture, and others.
Rather than replacing these architectures, Clprolf acts as an additional layer between Object-Oriented Programming (OOP) and software architecture. Its purpose is to complement, clarify, and reinforce existing architectural principles by making class roles and inheritance relationships more explicit.
In this way, Clprolf helps improve architectural consistency while remaining fully compatible with established design practices.
Furthermore, Clprolf is not just meant for enterprise software, but for all types of applications, including simulations and scientific applications.

XII) Summary

Clprolf introduces very few concepts.

Classes

ClAgent
ClWorker
ClSystem
ClDraft

Interfaces

ClFamily
ClTrait
ClFree

Two Fundamental Rules

1. Separate business and technical concerns.
2. Inherit only within the same domain.

Clprolf — Quick Start

Charles Koffler — Thu, 16 Apr 2026 10:43:05 +0000

Clprolf stands for CLear PROgramming Language and Framework.

"Don't use it - You don't need it!"

Clprolf is both a Java and C# architectural framework designed to make architectural intent visible within object-oriented systems.

It acts as a lightweight structural layer between pure OOP and your architecture (DDD, Clean, Hexagonal, etc.).

🎯 The Problem

In traditional object-oriented systems, class responsibilities often become unclear over time. A class may start with a well-defined purpose, but gradually accumulate business rules, technical implementation details, and unrelated infrastructure logic. As systems grow, architectural intent drifts.

💡 The Clprolf Approach

Clprolf encourages developers to identify and express the primary responsibility of each class. The framework is based on a simple idea:

A class should clearly express its primary role.

🧱 Class Roles

`ClAgent`

Represents a business or conceptual class. It contains business logic, orchestrates processes, and makes decisions. Entities and DTOs are classified as agents since they represent domain data.

@ClAgent
public class OrderProcessor {
    private OrderRepository repository;

    public void process(Order order) {
        if(order.total() <= 0) {
            throw new Error();
        }
        repository.save(order);
    }
}

`ClWorker`

Represents a technical service or infrastructure class. It exists solely to support agents through technical mechanisms (database access, application startup, OS interactions, parsing). It is not organized around a business domain.

@ClWorker
public class OrderRepository {
    public void save(Order order) {
        // Direct database access code here
    }
}

`ClSystem` (Optional)

Represents a system-oriented agent or components at the boundaries of the application (e.g., Sockets, Files, HTTP Controllers, Middlewares). It bridges system behaviors and naturally orchestrates or uses standard agents.

`ClDraft`

An object without a defined role yet. Used during prototyping or heavy refactoring when the destination of the class isn't clear.

🧩 Flexibility & Tailored Adoption

Clprolf acts primarily as a structural guide rather than a rigid architectural framework. It is designed to adapt to your project, not the other way around.

1. Step-by-Step Integration

You don't have to adopt everything on day one:

Step 1: Classes First. Focus exclusively on separating @ClAgent (or ClSystem) and @ClWorker. This allows your team to clean up the codebase without friction.
Step 2: Interfaces Later (Optional). The interface system (ClFamily, ClTrait) can be introduced in a second phase. If you find it too unconventional for your habits, you can completely ignore it. The framework remains 100% effective just with class annotations.

2. Custom Terminology (Agnostic Naming)

If the words Agent or Worker do not match your team's culture, you can change them! Because the automated ArchUnit checker relies on the underlying types, a simple automated Rename in your IDE allows you to adapt the vocabulary:

Default Role	Conceptual Alternative	Technical Alternative
`@ClAgent`	`@ClConcept`	`@ClDomain`
`@ClWorker`	`@ClMechanism`	`@ClInfrastructure`
`@ClSystem`	`@ClBridge`	`@ClLowLevel`

🧠 Inheritance & Domain Preservation

Clprolf enforces inheritance only between classes belonging to the same conceptual domain.

// ✅ VALID: Same domain continuity
@ClAgent public class Animal {}
@ClAgent public class Dog extends Animal {}

// ❌ DISCOURAGED: Mixing technical and conceptual worlds
@ClWorker public class AppLauncher {}
@ClAgent public class Dog extends AppLauncher {} // Use Composition instead!

🔗 Interfaces

Clprolf extends this philosophy to abstractions by introducing three categories, which also declare a target role (@ClAgent or @ClWorker) to maintain structural continuity:

ClFamily: Represents an abstract family of related implementations (mirrors pure abstract classes).
ClTrait: Represents a cross-cutting, shared capability across multiple families.
ClFree: A generic, unrestricted interface for external integrations.

🛠 nighttime Automated Validation (ArchUnit & ArchUnitNET)

Clprolf includes an open-source semantic checker for Java and .NET. It does not enforce rigid package structures. It only ensures your classes respect their declared identities and inheritance rules through 8 standard automated tests.

🔚 In One Sentence

Clprolf makes explicit what many developers already try to enforce implicitly.

🧱 Two Structural Principles Behind Clprolf

Charles Koffler — Tue, 24 Feb 2026 12:48:40 +0000

Prerequisites

Clprolf builds upon classical Object-Oriented Programming.

To fully understand this article, readers should already be familiar with:

the fundamentals of OOP,
inheritance and composition,
common design principles such as SRP,
the guideline "favor composition over inheritance".

Clprolf is built around two central principles.

1. A class is either business/conceptual or technical

Every class belongs to one of the following worlds:

Business / Domain World

The class represents a business or conceptual responsibility.

Examples:

order management,
business logic,
simulation,
functional orchestration,
but also system-oriented agents.

These classes are declared using:

@ClAgent

Technical World

The class performs a technical task executed by the system:

database access (via system agents),
networking (often by utilizing low-level agents),
file handling (most frequently with system-oriented agents),
display / rendering,
infrastructure,
no conceptual domain; it is just the system executing technical agents or starting an application,
generally a system technical service associated with an agent.

These classes are declared using:

@ClWorker

2. Inheritance must preserve the domain

A class should only inherit from another class belonging to the same conceptual domain.

Otherwise:

composition should be used.

This principle prevents incoherent hierarchies and mixed responsibilities.

Relation to SRP

The Single Responsibility Principle (SRP) states that a class should have only one reason to change.

The concept of class domain provides a structural way to think about that responsibility.

If a class remains organized around a single domain, its evolution tends to remain coherent.

Clprolf does not replace SRP.

Instead, it provides a vocabulary for expressing responsibility through domain continuity.

Relation to "Favor Composition Over Inheritance"

The guideline "favor composition over inheritance" is widely accepted in object-oriented design.

Clprolf introduces a structural criterion for applying it.

When inheritance preserves the same class domain, it may be appropriate.

Example:

Animal
  └─ Dog

Both classes belong to the same conceptual domain.

However:

Dog
  └─ DatabaseConnection

introduces a different domain.

In such cases, composition generally provides a clearer relationship.

The principle does not eliminate developer judgment.

It simply evaluates inheritance through domain continuity.

Why This Matters

As systems evolve, responsibilities tend to drift.

Classes gradually accumulate unrelated concerns and architectural intent becomes harder to identify.

By making domains explicit and by relating inheritance to domain continuity, Clprolf encourages structures that remain understandable over time.

The goal is not to restrict developers.

The goal is to make architectural decisions visible and easier to reason about.

Closing

These two principles form the foundation of Clprolf.

They define how classes are interpreted and how inheritance is understood within the framework.

From them emerge the structural distinctions that Clprolf makes explicit:

domain-oriented classes (ClAgent),
technical support classes (ClWorker),
coherent inheritance,
explicit architectural responsibilities.

Everything else in Clprolf builds upon these two ideas.

Preventing Architectural Drift in Object-Oriented Systems with Clprolf framework

Charles Koffler — Sun, 15 Feb 2026 12:32:55 +0000

A Structural Approach with Clprolf framework

Most large object-oriented systems do not collapse because developers lack expressive tools.

They collapse because of architectural drift.

A class is created with a clear intention.
Over time, new responsibilities are added.
Technical code enters domain classes.
Domain decisions appear inside infrastructure classes.
Inheritance is used for convenience instead of conceptual coherence.

The name of the class remains the same.

But its role has changed.

This is not necessarily a failure of developers.
It is often a structural weakness of unconstrained class design.

When the role of a class is only implicit, nothing prevents that role from drifting silently.

Clprolf addresses this problem by making the primary role of each class explicit.

1. Declaring the role of a class

In classical object-oriented programming, a class is often introduced only by its name:

class Sorter {
}

The name may suggest an intention, but the architecture does not know what kind of class it is.

Is it a domain object?
Is it a technical utility?
Is it an application coordinator?
Is it infrastructure?

Clprolf makes the role explicit:

@ClAgent
public class Sorter {
}

or:

@ClWorker
public class Sorter {
}

The class is no longer only a named container.

It declares its primary architectural role.

An agent carries conceptual meaning, domain behavior, application logic, simulation logic, or coordination.

A worker performs technical execution, for an agent( I/O, rendering, persistence, networking), launching, or system access.

The class becomes a class with a declared place in the architecture.

2. From description to commitment

A class name describes.

A Clprolf class role commits.

For example:

@ClAgent
public class OrderProcessor {
}

means:

This class carries conceptual or application responsibility.

And:

@ClWorker
public class OrderRepository {
}

means:

This class performs technical work.

That distinction matters because architectural drift often begins when a class slowly stops matching its original meaning.

A service starts doing persistence.
A repository starts making business decisions.
A UI class becomes the brain of the application.
A technical helper becomes a hidden domain object.

In traditional OOP, these shifts can happen silently.

In Clprolf framework, they become visible because the class has already declared what kind of role it is supposed to play.

The declaration does not remove human judgment.

But it gives judgment a structure.

3. Structural discipline, not convention

Many architectural principles already tell developers what to do:

separate concerns;
avoid God Objects;
respect layers;
apply SOLID;
keep technical code away from domain logic;
prefer composition when inheritance is conceptually wrong.

These principles are valuable, but they are often expressed as advice.

Clprolf framework turns part of this advice into structure.

It does not rely only on naming conventions or team memory.

It makes role separation visible in the code itself.

For example:

@ClAgent
public class CheckoutService {
}

@ClWorker
public class PaymentRepository {
}

The reader immediately sees the difference:

CheckoutService carries application meaning;
PaymentRepository performs technical work.

The code does not merely follow a convention.

It expresses an architectural decision.

4. Inheritance must respect the declared role

Architectural drift becomes especially dangerous through inheritance.

Inheritance is not just a way to reuse code.

It expresses conceptual continuity.

If a class inherits from another class, it says:

I belong to the same conceptual family.

That is why Clprolf enforces a simple rule:

A class should inherit only from another class belonging to the same coherent domain.

For example:

@ClAgent
public class Animal {
}

@ClAgent
public class Dog extends Animal {
}

This is coherent.

Dog remains in the same conceptual domain as Animal.

But this is not coherent:

@ClWorker
public class AnimalWorker {
}

@ClAgent
public class Dog extends AnimalWorker {
}

This inheritance mixes unrelated roles.

Dog is a conceptual object.
AnimalWorker is a worker aiding an agent.

The correct solution is composition.

The agent may use a worker, but it should not inherit from one.

5. Preventing silent migration across layers

In many systems, classes do not become problematic all at once.

They migrate slowly.

A class starts as domain logic.
Then it gets logging.
Then database calls.
Then formatting.
Then HTTP handling.
Then retry logic.
Then business decisions from another domain.

Eventually, the class still has the same name, but no longer the same responsibility.

Clprolf framework prevents this migration from being silent.

If a class is declared as an agent, technical work should remain secondary or be delegated to workers.

If a class is declared as a worker, it should not become the place where domain decisions are made.

An agent may contain a reasonable amount of technical code when that improves simplicity or readability, or having secondary domains.

A worker may call back an agent when acting as a bridge, for example in UI events, callbacks, or adapters.

But the primary role must remain clear.

6. Why this matters in large systems

In small systems, discipline is often enough.

A few developers can remember the intended design.

They know which classes are domain objects, which classes are technical, and which ones are temporary.

But large systems live longer than individual decisions.

Teams change.
Features accumulate.
Shortcuts become permanent.
Names stop reflecting reality.

In that context, implicit architecture is fragile.

Clprolf helps by making important architectural distinctions explicit:

agent  = conceptual meaning
worker = technical execution

This gives developers a shared vocabulary.

It also makes violations easier to detect, either manually during code review or automatically through tooling such as architecture tests.

A class can still be badly designed.

But it can no longer contradict its declared role silently.

7. Clprolf framework and architectural maintenance

Clprolf is not only useful when writing new code.

It is also useful during maintenance.

When a class becomes hard to understand, Clprolf encourages a simple question:

What is the primary role of this class?

If the answer is not clear, the class may temporarily remain an ClDraft.

If the answer becomes clear, it can be refactored into an agent, a worker, or several smaller classes with clearer responsibilities.

This makes refactoring more natural.

You do not need to classify everything perfectly from the beginning.

But over time, the codebase can move toward clearer roles.

Clprolf therefore helps prevent architectural drift in two ways:

by making roles explicit when classes are created;
by supporting refactoring when roles become clearer later.

8. What Clprolf framework does not do

Clprolf does not reduce what can be built.

It does not remove object-oriented programming.

It does not replace existing architectures such as MVC, Clean Architecture, or DDD.

It does not prevent developers from making decisions.

Instead, it makes those decisions visible.

Conclusion

Architectural drift is one of the main reasons object-oriented systems become difficult to maintain.

The problem is not that developers do not care about design.

The problem is that, in classical OOP, the role of a class is often only implicit.

Clprolf makes that role explicit.

An agent carries meaning.
A worker performs technical execution.
Inheritance must preserve conceptual coherence.
Composition is used when domains diverge.

The result is not heavier architecture.

It is clearer architecture.

Clprolf does not merely describe responsibility.

It gives responsibility a visible place in the structure of the code.

And in long-lived systems, that visibility can be decisive.

Refactoring Your Classes with Clprolf framework

Charles Koffler — Thu, 25 Dec 2025 14:51:46 +0000

Most developers agree on the Single Responsibility Principle (SRP).
The real difficulty is not what to do — it’s when to do it.

In real projects, we usually:

write code that works,
understand it better over time,
refactor when responsibilities become clearer.

Clprolf framework fits naturally into this workflow by supporting postponed architectural decisions through refactoring.

1️⃣ Starting from a Classic OOP Class

Let’s start with a very common example.
Nothing exotic. Just a class that works.

public class OrderManager {

    public void processOrder(Order order) {
        if (order.getTotal() <= 0) {
            throw new IllegalArgumentException("Invalid order");
        }

        saveToDatabase(order);
        logOrder(order);

        String message = formatConfirmation(order);
        sendEmail(message);
    }

    private void saveToDatabase(Order order) {
        System.out.println("Saving order " + order.getId());
    }

    private void logOrder(Order order) {
        System.out.println("Order processed: " + order.getId());
    }

    private String formatConfirmation(Order order) {
        return "Order #" + order.getId() + " confirmed";
    }

    private void sendEmail(String message) {
        System.out.println("Sending email: " + message);
    }
}

This class:

contains business rules,
handles persistence,
performs logging,
formats messages,
sends emails.

Everyone has written something like this.

2️⃣ Using Clprolf framework Without Thinking About Roles

In Clprolf, you can start exactly the same way.

No need to decide anything upfront.
You simply acknowledge that the architectural role is not yet clear.

@ClDraft
public class OrderManager {

    public void processOrder(Order order) {
        if (order.getTotal() <= 0) {
            throw new IllegalArgumentException("Invalid order");
        }

        saveToDatabase(order);
        logOrder(order);

        String message = formatConfirmation(order);
        sendEmail(message);
    }

    private void saveToDatabase(Order order) { }
    private void logOrder(Order order) { }
    private String formatConfirmation(Order order) { return ""; }
    private void sendEmail(String message) { }
}

At this stage:

nothing is forced,
no architectural commitment is made,
the code can remain like this for a while.

ClDraft behaves like classic OOP — but consciously.

3️⃣ Applying SRP After Understanding the Code

Later — exactly like in a classic SRP refactoring — you realize that this class mixes different responsibilities.

Concern	Nature
Business decision	Business
Persistence	Technical
Logging	Technical
Formatting / I/O	Technical

This is where Clprolf becomes useful.

4️⃣ Refactoring into Explicit Responsibilities

Before (ClDraft)

OrderManager
 ├─ business rule
 ├─ persistence
 ├─ logging
 └─ notification


After (SRP made explicit)

OrderProcessor (ClAgent)
 ├─ business decision

OrderRepository (ClWorker)
 └─ persistence

OrderNotifierWorker (ClWorker)
 ├─ logging
 └─ messaging

🎯 Business Responsibility → `agent`

@ClAgent
public class OrderProcessor {

    private final OrderRepository repository;
    private final OrderNotifierWorker worker;

    public OrderProcessor(OrderRepository repository,
                          OrderNotifierWorker worker) {
        this.repository = repository;
        this.worker = worker;
    }

    public void process(Order order) {
        if (order.getTotal() <= 0) {
            throw new IllegalArgumentException("Invalid order");
        }

        repository.save(order);
        worker.notify(order);
    }
}

The agent:

expresses business intent,
coordinates actions,
contains no technical details.

⚙️ Technical Responsibilities → `worker`

@ClWorker
public class OrderRepository {

    public void save(Order order) {
        System.out.println("Saving order " + order.getId());
    }
}

@ClWorker
public class OrderNotifierWorker {

    public void notify(Order order) {
        log(order);
        String message = format(order);
        send(message);
    }

    private void log(Order order) {
        System.out.println("Order processed: " + order.getId());
    }

    private String format(Order order) {
        return "Order #" + order.getId() + " confirmed";
    }

    private void send(String message) {
        System.out.println("Sending email: " + message);
    }
}

Workers may group related technical concerns when they serve the same technical purpose:

I/O,
formatting,
logging,
infrastructure.

This is acceptable because business meaning remains in the agent. And because most of the time, the worker supports an agent.

5️⃣ What Changed — and What Didn’t

❌ What did not change

algorithms,
behavior,
performance,
expressivity.

✅ What did change

responsibilities became explicit,
architectural intent became visible,
future evolution became easier.

This is simply SRP applied structurally.

🧩 Conclusion

Clprolf framework does not ask developers to think harder —
and not earlier.

You can:

write code first,
understand it later,
refactor responsibilities when needed.

ClDraft is not a goal —
it is a temporary state that supports real-world development.

Clprolf framework can work as a refactoring tool for architectural clarity.

Clprolf Framework — Global Model

Charles Koffler — Sat, 06 Dec 2025 15:55:51 +0000

Clprolf framework introduces simple class roles to clarify the natural place of each class in a project.

Many developers understand the basic distinction:

an agent carries meaning, intention, or domain behavior;
a worker is a system service and performs technical execution.

But when a project grows, another question appears:

How do these classes relate to each other globally?

This document provides a conceptual overview of how the main Clprolf roles interact in practice.

It explains:

how agents and workers depend on each other;
how domain-level classes stay separated from technical classes;
how system-oriented objects such as streams, sockets, files, or threads can be understood;
how workers act as bridges between conceptual objects and low-level execution.

This is not a formal compiler rule-set.

It is a mental model: a guide that helps developers classify new classes more naturally and understand Clprolf architecture as a whole.

1. The basic idea

The core model is simple:

Agent  = meaning
Worker = execution

An agent represents something conceptually meaningful in the program.

A worker is a system service. It performs the technical work needed to support agents, the application, or the system.

In many systems, we also encounter classes that are close to the operating system or runtime, but still have a conceptual identity.

Examples:

Stream
Socket
Thread
Channel
File
Window
Button

These can be understood as system-oriented agents.

They are still agents because they represent conceptual objects, but their internal behavior often depends on low-level workers.

A system-oriented agent is not necessarily a new official class role.

It is a conceptual category:

an agent whose domain is connected to a system capability.

2. Global conceptual diagram

┌────────────────────────────────────────────────────┐
│                       AGENT                        │
│       conceptual behavior, domain responsibility   │
│                                                    │
└─────────────────────────┬──────────────────────────┘
                          │
                          │ uses / delegates to
                          ▼
┌────────────────────────────────────────────────────┐
│                       WORKER                       │
│          system service for technical execution      │
│               serving an agent                     │
└─────────────────────────┬──────────────────────────┘
                          │
                          │ may use
                          ▼
┌────────────────────────────────────────────────────┐
│              (SYSTEM-ORIENTED) AGENT               │
│   conceptual object connected to system behavior   │
│   examples: stream, socket, thread, file, window   │
└─────────────────────────┬──────────────────────────┘
                          │
                          │ delegates low-level work to
                          ▼
┌────────────────────────────────────────────────────┐
│                    (LOW-LEVEL) WORKER              │
│     native call, rendering, I/O, OS/runtime work   │
└────────────────────────────────────────────────────┘

This diagram should not be read as a strict one-way call graph.

It shows the natural direction of responsibility:

meaning → execution → system capability → low-level operation

3. Agent

An agent represents a meaningful object or behavior.

It carries intention, responsibility, and conceptual identity.

Examples:

OrderProcessor
CheckoutService
Snake
FoodExpert
WindowObserver
Button
DirectoryExplorer
Animal

An agent answers questions such as:

What does this object mean?
What responsibility does it carry?
What behavior belongs to its domain?

Agent guidelines

An agent may:

call other agents;
delegate technical work to workers;
hold domain state;
express business, application, simulation, or UI meaning.

An agent should avoid:

directly performing heavy technical work;
depending directly on low-level system mechanisms when a worker can handle them;
becoming a mixed class where domain decisions and technical execution are indistinguishable.

If an agent needs system-level behavior, it usually delegates it to a worker.

4. Worker

A worker performs technical execution. It is a system service.

It does not primarily represent a domain concept.
It performs work for an agent, the application, or the system.

Examples:

OrderRepository
FileWriterWorker
DatabaseWorker
RendererWorker
Launcher
SocketWorker
SwingRenderer
DirectoryExplorerWorker

A worker answers questions such as:

What technical operation must be performed?
What system, framework, I/O, or rendering mechanism must be called?
What concrete execution is needed by an agent?

Worker guidelines

A worker may:

call other workers;
use system-oriented agents;
perform I/O, rendering, persistence, networking, or launching;
call back an agent when acting as a technical bridge, such as in UI events, callbacks, adapters, or asynchronous notifications.

A worker should avoid:

containing domain decisions;
becoming the conceptual brain of the application;
hiding business rules inside technical code.

A worker can bridge the domain world and the system world, but it should not absorb the domain.

5. System-oriented agent

A system-oriented agent is an agent whose conceptual domain is connected to a system capability.

It is not simply a worker, because it represents an object with meaning.

Examples:

a Stream represents a flow of data;
a Socket represents a communication endpoint;
a Thread represents an execution path;
a File represents a filesystem object;
a Window represents a visible interaction space;
a Button represents a clickable UI object.

These objects are conceptually meaningful.

However, their implementation often requires technical operations:

native calls,
OS interaction,
rendering,
I/O,
event dispatching,
memory or runtime management.

That low-level work should be handled internally by workers.

System-oriented agent guidelines

A system-oriented agent may:

expose conceptual methods such as open(), read(), write(), click(), show(), or close();
delegate its technical realization to workers;
interact with other system-oriented agents in the same coherent system domain.

A system-oriented agent should avoid:

calling unrelated domain agents directly;
mixing high-level business decisions with low-level system mechanics;
exposing technical implementation details as its main identity.

The key idea is:

A system-oriented agent represents a system capability as a meaningful object.
A worker performs the low-level execution behind it.

6. Summary table

Here is a simplified model of direct usage.

From / To	Agent	Worker	System-oriented agent
Agent	Yes	Yes	Usually no
Worker	Controlled callback / bridge	Yes	Yes
System-oriented agent	Usually no	Yes	Yes, if same system domain

This table is a guide, not a rigid rule-set.

The important idea is not to forbid every possible dependency.

The important idea is to preserve the direction of meaning:

agents carry meaning
workers execute
system-oriented agents represent system capabilities
low-level workers perform the technical realization

7. Purpose of this model

This model helps developers:

classify new classes correctly;
avoid accidental mixing of concerns;
navigate complex systems more safely;
recognize patterns inside existing codebases;
understand why some system classes still feel like agents;
decide when a UI object, listener, socket, stream, or file should be modeled as an agent or as a worker.

It also explains why Clprolf is not just:

business = agent
technical = worker

The real model is slightly richer:

agent  = conceptual meaning
worker = technical execution

Some conceptual objects are close to the system.

That does not automatically make them workers.

A button can be an agent.
A listener can be an observer agent.
A stream can be a system-oriented agent.
Their rendering, event dispatching, or native operations can be workers.

8. Final synthesis

Clprolf gives each class a natural place.

At the highest level:

Agent  = meaning
Worker = execution

Then the model expands:

Domain agent
    → carries business, application, simulation, or UI meaning

Worker
    → performs technical execution

System-oriented agent
    → represents a conceptual system capability

Low-level worker
    → performs native, rendering, I/O, or runtime operations

This model keeps Clprolf simple while explaining real-world cases more accurately.

It avoids a false choice between “everything technical is worker” and “everything conceptual is pure business.”

Instead, it asks one practical question:

What is the main responsibility of this class?

If the class represents something meaningful, it is probably an agent.

If it mainly executes technical work, it is probably a worker.

That is the global logic of Clprolf.

Final line

Agents carry meaning.
Workers perform execution.
System-oriented agents represent meaningful system capabilities.
Together, they make architecture easier to read, reason about, and maintain.

Separating Class Responsibilities with Clprolf framework

Charles Koffler — Thu, 04 Dec 2025 18:06:42 +0000

Designing clean, well-structured classes is one of the central challenges of object-oriented programming.

Clprolf framework addresses this challenge by introducing class roles: a simple way to express the main role of a class and the kind of work it is expected to perform.

Clprolf does not replace your existing architecture.

Your repositories, services, controllers, entities, UI components, abstractions, and domain objects all stay where they are.

Clprolf framework simply adds an explicit role to each important class, making the separation between conceptual logic and technical execution easier to read, maintain, and verify.

The “class roles”

Clprolf framework uses class roles.

A class keeps its identity, but its class role tells us what kind of role it plays in the program.

In Clprolf, the two main class roles are:

agent
worker

They help distinguish between classes that carry conceptual meaning and classes that perform technical execution.

1. Two class roles for two kinds of work

Every significant class should declare its main class role.

`agent`

An agent is a class whose main responsibility is conceptual, domain-oriented, or meaningful in the application.

Examples:

business services,
domain objects,
controllers,
observers/listeners with a conceptual role,
UI objects that represent meaningful user interactions,
simulations,
application coordinators.

An agent may contain a small amount of technical code, or secondary domains, if it's practical.

However, heavy technical work should usually be delegated to workers.

`worker`

A worker is a class whose main responsibility is technical execution.

Examples:

technical support classes for agent
repositories,
DAOs,
file access classes,
rendering workers,
launchers,
persistence classes,
console or system I/O,

A worker performs technical work for an agent, for the application, or for the system.

It should avoid becoming the place where domain decisions are made.

2. Class roles work with your existing architecture

Clprolf does not replace familiar architectural roles such as Service, Repository, Controller, Entity, View, or DAO.

It adds a class role on top of them.

A typical mapping could be:

Existing component	Clprolf class role
Service	`agent`
Controller	`agent`
Entity / domain object	`agent`
Repository / DAO	`worker`
Launcher	`worker`
Renderer / low-level display code	`worker`

This mapping is not meant to erase architectural nuance.

Different teams may interpret certain components differently.

For example, controllers may be treated as application agents because they coordinate meaningful behavior.
But in some architectures, a controller may be treated as a purely technical endpoint.

Clprolf allows that flexibility, as long as the choice remains clear and consistent.

3. Domain consistency through inheritance rules

Because a class declares its main role, inheritance can be checked for coherence.

The basic rule is simple:

A class should inherit only from a class belonging to the same coherent role or domain.

Allowed

@ClAgent
public class Animal {
}

@ClAgent
public class Dog extends Animal {
}

This is coherent: Dog remains in the same conceptual family as Animal.

Not allowed

@ClWorker
public class ClientDAO {
}

@ClAgent
public class Dog extends ClientDAO {
}

This is not coherent.

Dog represents a conceptual domain object.
ClientDAO represents technical class for database calls.

The issue is not inheritance itself.
The issue is incoherent inheritance across unrelated roles.

Clprolf makes this kind of mismatch visible and, depending on the implementation, checkable through language rules, tooling, or architecture tests.

4. Why this is useful in practice

With Clprolf class roles:

conceptual logic and technical execution stay easier to separate;
class hierarchies are less likely to drift into incoherent states;
technical classes are less likely to absorb domain decisions;
agents are encouraged to delegate heavy technical work to workers;
roles become easier to understand for developers joining the project;
architectural discussions become more concrete.

Instead of asking vaguely:

“Is this class clean?”

we can ask:

“Is this class coherent with its declared class role?”

That question is much easier to discuss, review, and automate.

5. Class roles and SOLID

Class roles are only one part of Clprolf, but they support a powerful idea:

Each object should express a unique and well-defined kind of work.

This aligns naturally with the Single Responsibility Principle.

A class belongs to one main role, expressed through its class role.
Its methods should then remain coherent with that role.

This does not mean a class must have only one method.

It means that its methods should serve the same overarching responsibility.

For example, an agent may have several methods, as long as those methods serve the same conceptual role.

A worker may have several methods, as long as those methods remain focused on technical execution.

Clprolf interfaces can also target these roles.

For example:

@ClAgent
@ClFamily
public interface PaymentService {
}

@ClWorker
@Family
public interface PaymentRepository {
}

This allows family and trait interfaces to match the intended role of the classes that implement them.

As a result, developers can define both:

what kind of object a class is;
what kind of work it is expected to perform.

All while staying compatible with established object-oriented and SOLID principles.

6. How does this relate to DDD or Clean Architecture?

Clprolf does not replace Domain-Driven Design or Clean Architecture.

It works alongside them.

DDD focuses on modeling the business domain, defining concepts, language, and boundaries.

Clean Architecture focuses on separating domain logic from technical concerns through layers and dependency rules.

Clprolf works at a more local level:

It makes the main role of each class explicit.

Clprolf is close to Clean Architecture in spirit, because it also tries to preserve clean boundaries between conceptual logic and technical execution.

The difference is that Clprolf expresses those boundaries directly in the code through class roles.

The framework allows to check with ArchUnit the application of the Clprolf annotations.

So Clprolf does not require developers to rely only on discipline and convention.

It gives teams a structure that can be read, discussed, and verified.

Summary comparison

Approach	Main focus	Boundary enforcement
DDD	Domain modeling, ubiquitous language, bounded contexts	Mostly conventions and team discipline
Clean Architecture	Separation of domain and technical concerns	Guidelines, layers, dependency rules
Clprolf framework	Class roles: explicit class roles such as `agent` and `worker`	Annotations and architecture tests

7. Examples

Below are simple examples using the Clprolf Java framework.

They show how class roles integrate naturally into everyday Java classes.

Example 1 — A service using a repository

@ClAgent
public class OrderService {

    private final OrderRepository repository = new OrderRepository();

    public void validateAndStore(String orderId) {
        // Application/domain logic
        if (orderId == null || orderId.isBlank()) {
            throw new IllegalArgumentException("Invalid order id");
        }

        // Technical operation delegated to a worker
        repository.save(orderId);
    }
}

OrderService carries application logic and delegates technical persistence to a worker.

Example 2 — A repository

@ClWorker
public class OrderRepository {

    public void save(String orderId) {
        // Technical persistence code
        System.out.println("Saving order " + orderId);
    }
}

OrderRepository performs technical work.

It does not decide whether the order is valid.
It simply saves what it is asked to save.

Example 3 — Forbidden inheritance

@ClWorker
public class WrongRepository extends OrderService {
    // Not coherent:
    // a technical worker should not inherit from an agent service.
}

Clprolf prevents, or at least highlights, this kind of cross-role inheritance.

A technical class should not extend a conceptual service.

Composition should be used instead.

Example 4 — A simple domain agent

@ClAgent
public class Animal {

    public void eat(String food) {
        System.out.println("The animal eats " + food);
    }

    public void sleep() {
        System.out.println("The animal sleeps");
    }
}

Animal is an agent because it represents a conceptual object.

It can have several methods because they remain coherent with the same domain.

Example 5 — A checkout service

@ClAgent
public class CheckoutService {

    private final OrderRepository orders = new OrderRepository();
    private final PaymentRepository payments = new PaymentRepository();

    public void checkout(String orderId) {
        if (orderId == null || orderId.isBlank()) {
            throw new IllegalArgumentException("Invalid order id");
        }

        orders.save(orderId);
        payments.process(orderId);
    }
}

@ClWorker
public class PaymentRepository {

    public void process(String orderId) {
        // Technical payment operation
        System.out.println("Processing payment for order " + orderId);
    }
}

The checkout service coordinates the application action.

The repositories perform technical operations.

8. What these examples demonstrate

These examples show that:

you keep your usual components: services, repositories, controllers, entities, launchers;
Clprolf framework adds a clear role through @ClAgent or @ClWorker;
agents may use workers through composition;
workers should not absorb domain decisions;
inheritance stays coherent;
class roles become easier to read and maintain.

Clprolf does not make architecture heavier.

It makes architectural intent visible.

Final line

Class roles are one part of Clprolf framework: they give objects a clear type of work, support clean separation between conceptual and technical responsibilities, remain compatible with SOLID, and can be targeted by Clprolf interfaces.

“One Reason to Change” — The SRP in Clprolf Framework

Charles Koffler — Thu, 13 Nov 2025 15:26:48 +0000

1. Trying to precise SRP

The Single Responsibility Principle (SRP) is quoted everywhere.

Its famous sentence —

“A class should have only one reason to change.”

— is powerful, but also ambiguous.

What is a reason?
Whose responsibility are we talking about?
And where does that responsibility come from?

The SRP was never false.
It simply stopped before naming the source of responsibility.

That is where Clprolf steps in: not to oppose the SRP, but to complete its logic.

2. What the SRP really implies

If all methods of a class should change for the same reason, then they must all participate in the same coherent work.

That leads to two important consequences:

Technical and conceptual responsibilities must not be mixed randomly.
A database driver change should not affect business rules.
A business rule change should not force a refactoring of low-level technical code.
Each class must have one main meaning.
This meaning unites its methods, gives the class its identity, and defines its natural scope.

In other words, respecting the SRP means respecting both:

separation of concerns
and
unity of meaning

A class is not coherent because it has few methods.
It is coherent because its methods serve the same main responsibility.

3. Responsibility belongs to the class, not to isolated methods

Responsibility does not live in methods individually.

Each method performs a specific action, but the class itself carries the overarching responsibility.

Example:

A Doctor class has one main responsibility: caring for the health of patients.

Its methods may be:

takeBloodPressure()
prescribeTreatment()
analyzeResults()

These methods do different things, but they all serve the same responsibility.

They are not separate responsibilities.
They are different expressions of one coherent duty.

Methods express the responsibility.
They do not define it by themselves.

Confusing method-level actions with class-level responsibility is what leads to fragmentation, over-engineering, and endless SRP debates.

4. "SRP does not mean “one method per class”

A common misunderstanding says:

“A class should do only one thing, so it should have only one method.”

This is not SRP.
It is a reduction of SRP.

An object is defined by a set of related operations belonging to the same conceptual domain.

A class may have many methods, and often should have many methods, as long as they all serve the same main meaning.

SRP is violated when a class mixes unrelated domains, not when it contains several methods belonging to the same one.

This confusion comes from treating “responsibility” as an isolated action, instead of understanding it as:

a conceptual duty flowing from what the class is meant to represent.

5. The chain of meaning: Change → Responsibility → Nature

A class does not change for arbitrary reasons.

It changes because its responsibility evolves.

And that responsibility exists because the class has a main conceptual nature: what the class is meant to represent in the program.

Example:

The way a doctor takes blood pressure might change:

a new device,
a new procedure,
a new medical standard.

But the reason for the change remains the same:

protecting and improving the patient’s health.

The technical details may evolve, but the responsibility remains coherent because it is rooted in the same conceptual nature.

So when we say:

“A class should have only one reason to change,”

we are really saying:

Change belongs to responsibility, and responsibility belongs to nature.

When this hierarchy is respected, evolution no longer breaks the class.
It confirms its role.

6. Where Clprolf framework could bring clarity

This is exactly where Clprolf goes beyond discussion.

Clprolf does not merely interpret the SRP.
It makes its intention visible.

In Clprolf:

every class declares its main role;
that role reveals the class’s conceptual nature;
its responsibility flows from that domain;
its methods are expected to remain coherent with that responsibility.

A class is no longer just a block of code.
It declares what kind of object it is.

For example:

@ClAgent
public class Doctor {
}

This says:

Doctor is an agent: a conceptual object carrying domain meaning.

And:

@ClWorker
public class OrderDAO {
}

This says:

OrderDAO is a worker: a technical performer serving execution.

Clprolf framework does not make bad design impossible.
But it makes incoherence visible.

The class has declared its role, so any contradiction becomes easier to see, discuss, test, or even detect automatically.

7. From moral advice to structural clarity

SRP often remains a moral principle:

“Try to keep your classes focused.”

With Clprolf framework, the principle becomes structural:

@ClAgent
public class OrderProcessor {
}

@ClWorker
public class OrderRepository {
}

The code itself starts to say:

This class carries conceptual logic.
This class performs technical work.

That does not remove judgment.
But it gives judgment a concrete basis.

Instead of asking vaguely:

“Does this class respect SRP?”

we can ask:

“Does this class remain coherent with its declared role?”

That is much easier to reason about.

8. Agents, workers, and practical flexibility

Clprolf should not be understood as a rigid purity system.

An agent is a class whose main responsibility is conceptual, domain-oriented, or meaningful in the application.

A worker is a class whose main responsibility is technical execution: launching, displaying, storing, rendering, sending, reading, writing, or interacting with the system.

An agent may contain a small amount of technical code if it remains secondary and improves readability.

But heavy technical work should usually be delegated to workers.

Likewise, a worker should avoid making domain decisions.
It may manipulate data, perform I/O, render output, or call technical APIs, but it should not become the brain of the application.

The rule is not:

“Agents must be perfectly pure.”

The rule is:

The main role must stay clear.

That is what makes Clprolf practical.

9. Method-level SRP: the real issue

SRP also has a meaningful application at the method level, but not in the simplistic way people often describe.

The key rule is:

A business method should not be polluted with heavy technical code.
A technical method should not contain domain decisions.

When a method mixes domain logic with infrastructure logic, it immediately gains two independent reasons to change:

the domain rules may evolve;
the technical mechanism may evolve.

That is a real SRP violation.

Example of a problematic method:

public void processOrder(Order order) {
    if (order.total() <= 0) {
        throw new IllegalArgumentException();
    }

    Connection connection = DriverManager.getConnection(...);
    PreparedStatement statement = connection.prepareStatement(...);
    statement.executeUpdate();
}

This method mixes:

order validation,
database connection,
SQL execution.

The method has more than one reason to change.

In Clprolf framework, the preferred structure would be:

@ClAgent
public class OrderProcessor {
    private OrderRepository repository;

    public void process(Order order) {
        if (order.total() <= 0) {
            throw new IllegalArgumentException();
        }

        repository.save(order);
    }
}

@ClWorker
public class OrderRepository {
    public void save(Order order) {
        // technical persistence code
    }
}

Now the roles are clear:

the agent decides;
the worker executes.

10. What does not violate SRP

Many things often called “SRP violations” are not necessarily violations.

For example:

a method that is long;
a method with several internal steps;
a method that contains an inline algorithm;
a class with several related methods;
a class that performs several actions within the same coherent domain.

These are not automatically SRP problems.

Algorithmic steps do not create multiple responsibilities by themselves.

A method can have several steps and still express one intention.

A class can have several methods and still serve one responsibility.

SRP is about cross-domain evolution, not micro-method minimalism.

The question is not:

“Is there more than one line?”
“Is there more than one method?”

The question is:

Are multiple unrelated reasons to change being mixed together?

11. Clprolf framework and inheritance coherence

SRP is also related to inheritance.

Inheritance is not just code reuse.
It expresses conceptual continuity.

If a class inherits from another class, it should remain in the same coherent domain.

For example:

@ClAgent
public class Animal {
}

@ClAgent
public class Dog extends Animal {
}

This is coherent: Dog remains in the same conceptual family as Animal.

But this is not coherent:

@ClWorker
public class DatabaseConnection {
}

@ClAgent
public class Dog extends DatabaseConnection {
}

This mixes unrelated meanings.

The issue is not inheritance itself.
The issue is incoherent inheritance.

Clprolf makes this visible by giving each class a declared role.

If the inheritance crosses incompatible domains, the contradiction becomes obvious.

And if the developer really needs to force the relation, Clprolf can allow explicit forcing annotations — but the exception remains visible.

12. From SRP to Clprolf

The SRP says:

A class should have only one reason to change.

Clprolf framework asks:

Where does that reason come from?

And the answer is:

It comes from the class’s responsibility.
And that responsibility comes from its main nature, revealed by its declared role.

So Clprolf completes the SRP like this:

A class should have only one reason to change
because it has one main responsibility,
rooted in one main conceptual nature.

This does not replace the SRP.

It explains it.

It gives it structure.

It turns a slogan into something readable in code.

13. Summary table

Concept	Meaning	Example
Domain	What the class conceptually represents	`Doctor`
Responsibility	What the class is responsible for as a whole	Caring for patients
Methods	Concrete actions expressing the responsibility	`takeBloodPressure()`
Agent	Class with a conceptual/domain role	`OrderProcessor`
Worker	Class with a technical execution role	`OrderRepository`

When nature, responsibility, methods, and role stay aligned, change becomes more predictable.

The class can evolve without losing its identity.

14. Final note — Change as a sign of duty

Change is not always a sign of instability.

Sometimes, change is the proof that a class is still faithful to its duty.

A class evolves because the responsibility it carries evolves.

If the class has a clear nature, that evolution remains coherent.

If the class mixes unrelated responsibilities, every change becomes dangerous.

That is what the SRP was trying to say.

Clprolf framework helps to make it visible.

Conclusion

The SRP told us:

“A class should have only one reason to change.”

Clprolf tries to complete the sentence:

A class should have only one reason to change because its responsibility flows from one main nature, made visible by its declared role.

In the end, what the SRP truly asks for is simple:

no cross-domain mixing;
no incoherent inheritance;
no silent contradiction between what a class is and what it does;
one clear meaning given to each class.

That is the clarity Clprolf brings.

🗂️ Clprolf Framework Directory Explorer

Charles Koffler — Sun, 19 Oct 2025 21:24:37 +0000

Everyone knows that exploring directories can quickly turn into a messy technical exercise:
loops, recursion, stacks, file filters… and code that loses all readability.

With Clprolf framework, clarity is built-in.
Let’s see how a simple directory explorer can become a beautifully structured program.

💡 1. The Concept

We want to:

explore all subdirectories of a given folder,
in breadth-first order (level by level),
assign each directory a hierarchical ID,
and display the results cleanly.

Instead of mixing logic, display, and data handling,
Clprolf invites us to split them into roles.

Component	Declension	Responsibility
`Launcher`	`@ClWorker`	Starts the exploration
`DirectoryExplorerImpl`	`@ClAgent`	Performs the exploration
`DirectoryExplorerWorkerImpl`	`@ClWorker`	Displays results
`Directory`	`@ClAgent`	Represents one directory node
`DirectoryExplorer`	`@ClAgent @ClFamily`	The family of the agent
`DirectoryExplorerWorker`	`@ClWorker @ClFamily`	The family of the worker for the agent

⚙️ 2. The Launcher

The entry point is as simple as it looks.
It prepares the environment and delegates the job to the proper agent.

@ClWorker
public class Launcher {

    public static void main(String[] args) {
        Path path = Paths.get(args.length > 0 ? args[0] : System.getProperty("user.home"));
        try { path = path.toRealPath(LinkOption.NOFOLLOW_LINKS); } catch (Exception ignored) {}

        if (!Files.isDirectory(path)) {
            System.err.println("Not a directory: " + path);
            System.exit(1);
        }

        DirectoryExplorer explorer = new DirectoryExplorerImpl();
        explorer.breadthFirstFolders(path);
    }
}

It’s clear who does what:
this worker doesn’t explore — it simply launches the agent.

🧭 3. The Agent — `DirectoryExplorerImpl`

Here lies the real exploration logic.
The agent collaborates with a worker, manipulates a model, and manages a queue.

@ClAgent
public class DirectoryExplorerImpl implements DirectoryExplorer {

    private DirectoryExplorerWorker worker;

    public DirectoryExplorerImpl() {
        this.worker = new DirectoryExplorerWorkerImpl();
    }

    public void breadthFirstFolders(Path directoryPath) {
        directoryPath = directoryPath.normalize().toAbsolutePath();

        List<Directory> foldersList = new ArrayList<>();
        Queue<Directory> directoryToExplore = new LinkedList<>();

        directoryToExplore.add(new Directory(directoryPath, List.of(0)));

        while (!directoryToExplore.isEmpty()) {
            Directory current = directoryToExplore.poll();
            foldersList.add(current);

            File[] files = current.getPath().toFile().listFiles();
            if (files != null) {
                int index = 0;
                for (File file : files) {
                    if (file.isDirectory()) {
                        List<Integer> newId = new ArrayList<>(current.getHierarchicalId());
                        newId.add(index);
                        directoryToExplore.add(new Directory(file.toPath().normalize().toAbsolutePath(), newId));
                        index++;
                    }
                }
            }
        }

        worker.displayResult(foldersList);
    }
}

Every part is crystal clear:

The queue defines a breadth-first traversal.
Each directory receives its own hierarchical ID.
The worker takes care of presentation.

No recursion, no confusion.

👷 4. The Worker

Responsible for showing the result, not for computing it.
Again, we separate doing from showing.

@ClWorker
public class DirectoryExplorerWorkerImpl implements DirectoryExplorerWorker {

    public void displayResult(List<Directory> foldersList) {
        for (Directory dir : foldersList) {
            String display = formatId(dir.getHierarchicalId()) + " : " + dir.getPath();
            System.out.println(display);
        }
    }

    private String formatId(List<Integer> id) {
        return "(" + String.join(", ", id.stream().map(String::valueOf).toArray(String[]::new)) + ")";
    }
}

Simple, explicit, human-readable.

📦 5. The Model

@ClAgent
public class Directory {
    private Path path;
    private List<Integer> hierarchicalId;

    public Directory(Path path, List<Integer> id) {
        this.path = path;
        this.hierarchicalId = id;
    }

    public Path getPath() { return path; }
    public List<Integer> getHierarchicalId() { return hierarchicalId; }
}

🤝 6. The interfaces

@ClAgent
@ClFamily
public interface DirectoryExplorer {
    void breadthFirstFolders(Path directoryPath);
}

@ClWorker
@ClFamily
public interface DirectoryExplorerWorker {
    void displayResult(List<Directory> foldersList);
}

🪶 7. Why it matters

Breadth-first exploration is only the example.
What matters here is how naturally the architecture expresses itself:

The launcher launches.
The agent explores.
The worker displays.

✨ Final Thoughts

In classical Java, you might have written a single class doing everything.

In Clprolf, each role finds its natural place.
The result is simple, explicit, and readable — even for someone who never wrote Java before.

Clprolf brings clarity back into architecture.

DEV Community: Charles Koffler

A Semantic Approach to WPF and MVVM with Clprolf framework

Introduction

The Core Concepts: Agents and Workers

The Code in Action

The Architecture Blueprint

Wiring the Ecosystem Together

Guarding the Architecture with ArchUnitNET

Conclusion

Securing Your Spring Boot Architecture: A Pragmatic Approach with Clprolf

Introduction

The Core Concept: Architectural Psychological Safety

A Practical Example: The Weather Observation API

1. The Pure Contract (Interface)

2. The Spring Boot Implementation

3. The Data Access Layer & Composite Identity

Automated Enforcement in the CI/CD Pipeline

Conclusion

Introducing the ArchUnit Checker for the Clprolf Framework

What is Clprolf?

Bringing Architecture into the Build Process

Ecosystem Symmetry (.NET vs Java)

Core Rules

1. A class cannot mix roles (clprolf_classes_must_not_mix_agent_and_worker)

2. Inheritance must not mix domains (agent_worker_inheritance_must_not_mix)

3. Family interfaces must match implementation roles (family_role_must_match_implementation)

4. Trait interfaces must extend only trait interfaces (trait_interfaces_must_extend_only_trait_interfaces)

5. Clprolf interfaces must declare a target role (clprolf_interfaces_must_have_target_role)

6. Inheriting interface roles must match trait target roles (inheriting_interface_role_must_match_trait_interface_target_role)

7. Family target roles must match inherited family interfaces (family_interface_target_role_must_match_inherited_family_interface)

8. Direct trait implementation must respect trait roles (trait_interface_role_must_match_direct_implementation)

Optional Strict Validation

Explicit Escapes: Granular Bypasses

Why It Matters

Clprolf — Official Documentation

Introduction

In Java (ArchUnit)

In C# (ArchUnitNET)

💡 Note for Framework Users (.NET vs Java)

I) The Two Fundamental Principles

1. A class is either business/conceptual or technical

Business / Domain World

Technical World

2. Inheritance must preserve the domain

II) Progressive Adoption and Customization

II.1) Step-by-Step Adoption

II.2) Tailoring the Terminology

III) Class Types

III.1) ClAgent

III.2) ClWorker

III.3) The Optional ClSystem Role

III.4) ClDraft

III.5) Primary Domain and Technical Code

III.6) An "Opinionated" Framework for the Agent/Worker Choice

Java Example Confirming the Clprolf Vision: java.io.File

IV) Inheritance

Valid Example

Discouraged Example

V) Flexibility

VI) Interfaces

VI.1) ClFamily

Example

VI.2) ClTrait

Business Example

Technical Example

VI.3) Illustration of the Interface Family / Implementation Parallel

VI.4) ClFree

Example

VI.5) Using Interfaces

VI.6) A Real-World Example of ClFamily and ClTrait Interfaces

VI.7) Note on Clprolf and the Interface Segregation Principle (ISP)

VII) General Architecture

VIII) Purpose of the framework

IX) ArchUnit Checker

1. Java Version (ArchUnit)

2. C# .NET Version (ArchUnitNET)

Rules to Follow

clprolf_classes_must_not_mix_agent_and_worker:

agent_worker_inheritance_must_not_mix

family_role_must_match_implementation

1. A class cannot mix roles (`clprolf_classes_must_not_mix_agent_and_worker`)

2. Inheritance must not mix domains (`agent_worker_inheritance_must_not_mix`)

3. Family interfaces must match implementation roles (`family_role_must_match_implementation`)

4. Trait interfaces must extend only trait interfaces (`trait_interfaces_must_extend_only_trait_interfaces`)

5. Clprolf interfaces must declare a target role (`clprolf_interfaces_must_have_target_role`)

6. Inheriting interface roles must match trait target roles (`inheriting_interface_role_must_match_trait_interface_target_role`)

7. Family target roles must match inherited family interfaces (`family_interface_target_role_must_match_inherited_family_interface`)

8. Direct trait implementation must respect trait roles (`trait_interface_role_must_match_direct_implementation`)

III.1) `ClAgent`

III.2) `ClWorker`

III.3) The Optional `ClSystem` Role

III.4) `ClDraft`

Java Example Confirming the Clprolf Vision: `java.io.File`

VI.1) `ClFamily`

VI.2) `ClTrait`

VI.4) `ClFree`

VI.6) A Real-World Example of `ClFamily` and `ClTrait` Interfaces

`ClAgent`

`ClWorker`

`ClSystem` (Optional)

`ClDraft`

🎯 Business Responsibility → `agent`

⚙️ Technical Responsibilities → `worker`