DEV Community: Charles Koffler

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 an ArchUnit-based checker for Java projects. Rather than relying solely on documentation, Clprolf's structural principles can be validated automatically during development.

What is Clprolf?

Clprolf 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
--------
Agent
Worker
Draft

Interfaces
----------
Family
Trait
Free

The framework is based on two fundamental principles:

Separate business concerns from technical concerns.
Preserve the conceptual domain through inheritance.

Bringing Architecture into the Build Process

Architectural guidelines are often written down, discussed, and eventually forgotten.

The ArchUnit checker takes a different approach: architectural rules become executable tests.

As a result, violations can be detected automatically from IntelliJ IDEA, Maven, or any CI/CD pipeline supporting JUnit.

Core Rules

The ClprolfArchTest checker validates the framework's core rules.

A class cannot be both Agent and Worker

@ClAgent
@ClWorker
public class InvalidClass {
}

A class must have a single primary role.

Inheritance must preserve the role

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

This reflects one of Clprolf's central principles:

inheritance should preserve the conceptual domain.

Family interfaces must match implementation roles

A class implementing a @ClFamily must have a role compatible with the target role of that interface.

For example, an @ClAgent family interface should normally be implemented by an @ClAgent class.

Trait interfaces may only extend other trait interfaces

A trait remains a trait throughout the hierarchy.

This keeps interface inheritance structurally coherent.

Clprolf interfaces must declare a target role

Every @ClFamily and @ClTrait must explicitly declare whether it belongs to the Agent world or the Worker world.

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

Inheriting interfaces must have a role compatible with inherited traits

When a @ClFamily or @ClTrait inherits from a @Trait_interf, its target role must be compatible with the role of the inherited trait.
For example, an @ClAgent family interface may inherit from an @ClAgent trait, but not from a @ClWorker trait.
Traits annotated with both @ClAgent and @ClWorker are considered compatible with either role.
The rule may be overridden using @ClBypass.

Family interfaces must have compatible inherited family interfaces

When a @ClFamily inherits from another @Family_interf, both interfaces must have compatible target roles.
For example, an @ClAgent family interface may inherit from another @ClAgent family interface, but not from a @ClWorker family interface.
This rule preserves the conceptual domain across family interface hierarchies.
The rule may be overridden using @ClBypass.

Direct trait implementation must respect trait roles

Although direct implementation of a @ClTrait by a concrete class is tolerated in non-strict mode, the class must still have a role compatible with the trait.

For example:

@ClAgent
public class Order implements Payable {
}

is valid if Payable is an @ClAgent trait.

However:

@ClAgent
public class Order implements Persistable {
}

is invalid if Persistable is a @ClWorker trait.

Traits annotated with both @ClAgent and @ClWorker are compatible with either type of class.

The rule may be overridden using @ClBypass.

Optional Strict Validation

A second checker, ClprolfStrictArchTest, provides stricter validation rules.

These rules are optional and intended for teams that want complete Clprolf classification across their codebase.

Every class should declare a Clprolf role

Each class should explicitly be:

@ClAgent

@ClWorker

@ClDraft

Every interface should declare a Clprolf role

Each interface should explicitly be:

@ClFamily

@ClTrait

@ClFree

Classes should not directly implement trait interfaces

Traits are intended to be inherited through family interfaces rather than implemented directly by concrete classes.

Classes should implement only one primary family interface

Clprolf encourages a structure where a concrete class implements a single primary family interface.

This does not remove multiple interface inheritance. Instead, multiple inheritance is moved to the family interface itself.

For example:

@ClAgent
@ClFamily
public interface Horse
        extends Animal,
                Mammal,
                Payable {
}

The concrete implementation remains simple:

@ClAgent
public class HorseImpl implements Horse {
}

This preserves the expressive power of multiple interface inheritance while maintaining a coherent structure for concrete classes.

Why It Matters

Many frameworks provide architectural recommendations.

Clprolf goes one step further by making those recommendations automatically verifiable.

The result is a framework whose structural rules can be checked continuously throughout development, helping teams maintain consistency as projects evolve.

For developers interested in architecture, ArchUnit, or lightweight approaches to object-oriented design, the Clprolf checker provides an interesting example of how architectural principles can become executable rules.

Clprolf — Official Documentation

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

Introduction

Clprolf("Clear PROgramming Language and Framework") is Java (or C#) framework.

Its goal is to make certain object-oriented programming best practices explicit, without introducing heavy architecture or a steep learning curve.

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.

I) The Two Fundamental Principles

Clprolf is built around two central principles.

1. A class is either business-oriented 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.

These classes are declared using:

@ClAgent

Technical World

The class performs a technical task:

database access,
networking,
file handling,
display,
infrastructure.

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) Class Types

Clprolf contains only three class types.

II.1) `ClAgent`

Represents a business or conceptual class.

An agent:

contains business logic,
orchestrates processes,
makes decisions,
avoids heavy technical code.

Note: entities and DTOs are typically classified as agents, since they represent domain data.

Example:

@ClAgent
public class OrderProcessor {

    private OrderRepository repository;

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

II.2) `ClWorker`

Represents a technical class.

A technical class is primarily intended to support agent classes rather than be organized around a class domain.
Workers provide technical support and infrastructure services. They may coordinate or use low-level agent classes 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:

provides technical support,
manages infrastructure and execution mechanisms,
contains technical code.

Example:

@ClWorker
public class OrderRepository {

    public void save(Order order) {

        // database access

    }
}

II.3) `ClDraft`

An object without a defined role.

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.

II.4) 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.

II.5) Freedom of Interpretation and framework Recommendations

The choice between agent and worker is left to the developer.

Some responsibilities may be interpreted differently depending on the adopted architectural vision.

For example, a connection may be represented:

as an agent if viewed as a functional abstraction;
or as a worker if viewed as a purely technical mechanism.

However, in these cases, Clprolf recommends using an agent. For example, for a Connection class:

an agent to represent the connection,
and delegate technical code to one or more worker classes.

III) Inheritance

A class only inherits from another class within the same domain.

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.

IV) 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.

V) 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.

V.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 { (...) }

V.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 worker Persistable {
    void save();
}

V.3) `ClFree`

A generic interface without a specific role.

Allows flexibility.

Example

@ClFree
public interface ExternalApi {
}

V.4) Interface Usage

In Clprolf, ClFamily interfaces are the equivalent of pure abstract classes.

They are intended to be implemented by one or more future Clprolf classes.

They therefore possess a target role (agent or worker).

A class may implement only one primary ClFamily at a time, and the role of the class must match the target role of the interface.

Clprolf therefore adopts a simple interface implementation model, in the same way that Java uses single class inheritance. Indeed, a ClFamily is always the structural reflection of its implementation. This notably enables systematic loose coupling.

However, multiple interface implementation is not removed; it is simply moved to the Family implemented by the class.

This family interface may itself inherit from multiple Family and/or Trait` interfaces.

As a result, interfaces that would otherwise have been implemented directly by the class are grouped at the level of its primary Family.

Clprolf therefore preserves the expressive power of multiple interface inheritance while maintaining a simple and coherent structure for concrete classes.

Trait interfaces express a capability shared among multiple Family interfaces.

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

Normally, a Trait may only be inherited by a Family, not directly by a class.

However, direct implementation of a Trait by a class remains tolerated in Clprolf, although discouraged.

text Concrete Class ↓ implements ClFamily ↓ inherits from ClTrait

A Family may inherit from multiple Family and/or Trait.

A Trait may inherit only from other Trait, since a trait remains a trait.

Interface inheritance may still be forced using @ClInterfaceBypass (or @ClBypass when forcing inheritance across different target roles).

V.5) 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:

`java
@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 {
// (...)
}

VI) General Architecture

Clprolf naturally encourages a simple architecture.

`text 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.

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 for the Clprolf Framework

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 the semantic rules of Clprolf.

The rules contained in ClprolfStrictArchTest are optional.
Likewise, annotation names can easily be customized if another vocabulary is preferred.

clprolf_classes_must_not_mix_agent_and_worker

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

agent_worker_inheritance_must_not_mix

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

family_interface_role_must_match_implementation

The target role of a @ClFamily must match the role of its implementing class (@ClAgent or @ClWorker).

Can be overridden using @ClBypass.

(non-strict mode) trait_interface_role_must_match_direct_implementation

A class that directly implements a trait must have a compatible role.

Can be overridden using @ClBypass.

Direct trait implementation is forbidden in strict mode.

trait_interfaces_must_extend_only_trait_interfaces

A @ClTrait may only extend other @ClTrait interfaces.

Can be overridden using @ClInterfaceBypass.

clprolf_interfaces_must_have_target_role

A @ClFamily must declare exactly one target role:
@ClAgent or @ClWorker.

A @ClTrait must declare at least one target role:
@ClAgent, @ClWorker, or exceptionally both.

inheriting_interface_role_must_match_trait_interface_target_role

Any interface (family or trait) inheriting from a trait must have a role compatible with that trait.

Can be overridden using @ClBypass.

family_interface_target_role_must_match_inherited_family_interface

Family interfaces inherited by another family interface must have a compatible target role, unless overridden with @ClBypass.

Stricter Rules

optional_all_classes_should_have_clprolf_role

Every class should declare a Clprolf role:
@ClAgent, @ClWorker, or @ClDraft.

optional_all_interfaces_should_have_clprolf_role

Every interface should declare a Clprolf interface role:
@ClFamily, @ClTrait, or @ClFree.

optional_class_should_not_implement_trait_directly

A class should not directly implement a @ClTrait.

Use @ClInterfaceBypass if this behavior is intentionally required.

optional_class_must_implement_only_one_family_interface

A Clprolf class should implement at most one @ClFamily.

Can be overridden using @ClInterfaceBypass.

X) 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.

XI) Summary

Clprolf introduces very few concepts.

Classes

`text Agent Worker Draft `

Interfaces

`text Family Trait Free `

Two Fundamental Rules

`text

Separate business and technical concerns.
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.

A structured approach to object-oriented programming.
Roles and responsibilities become explicit.

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

Its goal is not to replace classical OOP, but to make certain important distinctions explicit:

business or domain responsibilities versus technical/support responsibilities,
coherent inheritance versus composition,
the primary responsibility of a class.

🎯 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 additional concerns:

business rules,
technical implementation details,
infrastructure logic,
unrelated responsibilities.

As systems grow, architectural intent becomes harder to understand and maintain.

💡 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.

To support this idea, Clprolf introduces explicit class roles and structural guidelines.

🧱 Class Roles

`agent`

Represents a business or conceptual class.

An agent:

contains business logic,
orchestrates processes,
makes decisions,
avoids heavy technical code.

Note: entities and DTOs are typically classified as agents, since they represent domain data.

Example:

@ClAgent
public class OrderProcessor {

    private OrderRepository repository;

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

`worker`

Represents a technical class.

A worker:

provides technical support,
manages infrastructure and execution mechanisms,
contains technical code.

Example:

@ClWorker
public class OrderRepository {

    public void save(Order order) {

        // database access

    }
}

`draft`

An object without a defined role.

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.

🧠 Inheritance

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

@Agent
public class Animal {
}

@Agent
public class Dog extends Animal {
}

When domains do not match, composition is generally preferred.

@ClWorker
public class AppLauncher {
}

@ClAgent
public class Dog extends AppLauncher {
}

In this case, composition would usually provide a clearer design.

🔗 Interfaces

Clprolf extends the same philosophy to interfaces.

Three interface categories are available:

family — an abstract family of related implementations,
trait — a shared capability across multiple families,
free — a flexible interface.

Family and trait interfaces also declare a target role:

agent
worker

This allows abstractions to remain consistent with the roles of their implementations.

⚖️ What Clprolf Provides

By making roles explicit, Clprolf helps developers:

understand class responsibilities more quickly,
maintain clearer architectural boundaries,
build more coherent inheritance hierarchies,
reduce architectural drift over time.

The framework acts primarily as a structural guide rather than a rigid architectural framework.

🎯 When to Use Clprolf

Clprolf is well suited for:

teams that want a lightweight structural guide for object-oriented design without adopting a heavy architectural framework,
educational contexts focused on architectural clarity,
complex systems,
simulation and MAS-like applications,
long-lived codebases where explicit responsibilities and coherent inheritance are important.

⚖️ Philosophy

Clprolf intentionally introduces light structural constraints.

These constraints are not designed to restrict creativity, but to make architectural decisions explicit.

🔚 In One Sentence

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

Introducing Flexibility Without Losing Structure in Clprolf

Charles Koffler — Fri, 27 Mar 2026 20:12:58 +0000

Why a structured approach doesn’t have to be a barrier to entry.

Introduction

When introducing a structured approach like Clprolf, a common concern appears quickly:

“Do I have to rewrite everything?”
“Does this change how I usually code?”
“Is this too strict for real-world usage?”

These concerns are legitimate.

Most real-world codebases are not perfectly structured.
They mix domain logic and technical details.
They evolve under constraints.

So the question becomes:

Can Clprolf exist without forcing a complete rewrite?

Starting From Existing Code

Clprolf is based on two simple principles:

a class is either technical or organized around a well-defined domain
inheritance must preserve that domain — otherwise, composition is used

These principles provide structure.

But they do not require starting from scratch.

You can start from existing code.

Even when a class mixes concerns,
it still has a primary role.

That role defines its nature.

A Flexible Entry Point

Clprolf can be used in a more flexible way by default, as the compiler operates in this mode.

In this mode:

existing code remains valid
no immediate refactoring is required
no additional annotations are necessary

The goal is not to enforce structure immediately,
but to make it available.

Structure Still Exists

Flexibility does not remove the model.

The same principles still apply.

Even in mixed code:

the primary role of a class remains identifiable
domain and technical concerns are still distinct in nature

Clprolf does not ignore structure.
It simply does not force it upfront.

Strict and Flexible Clprolf

This leads to two ways of using Clprolf:

a flexible usage, closer to common practices
a strict usage, with stronger structural guarantees

The difference is not in the model itself,
but in how strictly it is applied.

Strict Clprolf makes the separation explicit.
Flexible Clprolf allows it to remain implicit.

Compatibility Between Both

Both approaches are fully compatible.

strict code works in all cases
flexible code integrates without issue

There is no fragmentation.

Clprolf remains a single model,
regardless of how strictly it is applied.

Gradual Evolution

In practice, adoption becomes natural.

Developers can:

start with their existing code
observe where responsibilities become unclear
introduce structure where it brings value

No forced transition is required.

Clprolf can be adopted progressively.

Working With Existing Libraries

Clprolf does not require external code to follow its model.

Libraries, frameworks, and APIs can be used as they are.

What matters is how they are integrated.

The structure lives in your code,
not in the code you depend on.

Final Thought

Clprolf is not about forcing a new way of coding.

It is about providing a clearer structure
that can be applied when needed.

You don’t need to change everything to start.
You can start where you are —
and move toward more structure when it makes sense.

🧱 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".

Foundational Principles of Clprolf

Clprolf is based on two core principles:

A class is either organized around a well-defined class domain or exists to provide technical support to other classes.
Inheritance must preserve the class domain; otherwise, composition should be used.

These principles define how Clprolf structures classes and relationships.

What Is a Class Domain?

A class domain is the central subject around which a class is organized.

It defines what the class fundamentally represents and what it is responsible for.

Examples include:

Animal
File
Connection
Parser
JsonSerializer
Scheduler
Controller
PdfGenerator
RandomGenerator
PaymentService
InventoryService

Each of these classes represents a coherent subject.

A class domain does not need to be business-related.

It may represent:

a business concept,
a system concept,
a technical concept,
a scientific concept,
a simulation entity,
a service,
or any other coherent subject.

Domain-Oriented Classes

A domain-oriented class represents something.

Its identity comes from the domain it models rather than from the technical services it performs.

Examples:

Animal
File
Connection
Parser
JsonSerializer
Scheduler
Controller
PdfGenerator
RandomGenerator
PaymentService
InventoryService

These classes remain meaningful even when considered independently.

In Clprolf, such classes are typically represented as agent.

Technical Support Classes

Some classes do not primarily represent a domain.

Instead, they exist to support one or more agents by providing technical capabilities.

Examples include:

launching agents,
executing technical procedures,
displaying information,
interacting with the operating system,
accessing platform-specific features,
providing infrastructure services.

Examples:

AnimalWorker
ApplicationLauncher
AgentLauncher
ProcessLauncher
SystemExecutor
NativeProcessRunner
OperatingSystemWorker
ControllerWorker

These classes are primarily defined by the support they provide.

Their purpose is to help agents perform technical operations.

In Clprolf, such classes are typically represented as worker.

Agents and Workers

A useful way to understand the distinction is:

agent  → represents a domain
worker → supports a domain

Example:

public agent Animal {

    private AnimalWorker worker;

    public void display() {
        worker.display(this);
    }

}

public worker AnimalWorker {

    public void display(Animal animal) {

        // rendering logic
        // platform-specific code
        // UI interaction

    }

}

The Animal agent represents the domain.

The AnimalWorker exists to provide technical support to that domain.

Another example:

public agent PaymentService {
}

public worker PaymentServiceLauncher {
}

The service itself represents a domain.

The launcher exists only to support its execution.

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 language.

From them emerge the structural distinctions that Clprolf makes explicit:

domain-oriented classes (agent),
technical support classes (worker),
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.

Getting Started with Clprolf: Structuring Responsibilities in OOP

Charles Koffler — Fri, 06 Feb 2026 17:35:37 +0000

Prerequisites

Clprolf (CLear PROgramming Language and Framework) builds upon classical Object-Oriented Programming.

To fully benefit from this guide, readers should already be familiar with:

the fundamentals of OOP,
inheritance and composition,
basic design principles.

Making Responsibilities Explicit

Clprolf is a Java and C# framework designed to make architectural roles explicit.

In many object-oriented systems, separation of responsibilities relies primarily on conventions and developer discipline.

As projects evolve, responsibilities may gradually become mixed, making the original architecture harder to understand and maintain.

Clprolf addresses this by making architectural intent part of the programming model itself.

Every class explicitly declares its nature.

Foundational Principles of Clprolf

Clprolf is based on two core principles:

A class is either technical or organized around a well-defined class domain.
Inheritance must preserve the class domain; otherwise, composition should be used.

These principles define how Clprolf structures classes and relationships.

What Is a Class Domain?

A class domain is the central subject around which a class is organized.

It represents what the class fundamentally models and what it is primarily responsible for.

Examples:

a File class belongs to a file-management domain,
a Connection class belongs to a connection-management domain,
a RandomGenerator class belongs to a random-generation domain,
an OrderProcessor class belongs to an order-processing domain.

Low-level technical abstractions such as File, Connection, Logger or Parser still possess their own class domain and are therefore typically modeled as agents.

A technical class is different.

A worker:

provides technical support,
manages infrastructure and execution mechanisms,
contains technical code.

1️⃣ Declaring a Nature

In classical OOP, a class is typically declared as:

public class OrderManager { }

In Clprolf, the architectural nature is made explicit:

@ClAgent
public class OrderProcessor { }

@ClWorker
public class OrderRepository { }

Each class declares its nature from the beginning.

The core natures are:

agent → domain-oriented responsibility
worker → support/technical responsibility
draft → temporary undefined responsibility

2️⃣ Starting Flexible with `draft`

Architectural clarity is not always immediate.

During prototyping or exploration, a class may begin as:

@ClDraft
public class OrderManager {

    public void process(Order order) {
        validate(order);
        save(order);
        notify(order);
    }

}

draft represents a temporary state.

The responsibility can be clarified later through refactoring.

3️⃣ Making Responsibilities Explicit

After analyzing the class, we identify several distinct responsibilities:

Responsibility	Nature
Order processing	Domain
Persistence	Technical
Notification delivery	Technical

The class can then be reorganized:

@ClAgent
public class OrderProcessor {

    private OrderRepository repository;
    private OrderNotifier notifier;

    public void process(Order order) {

        validate(order);

        repository.save(order);

        notifier.notify(order);
    }

}

@ClWorker
public class OrderRepository { ... }

@ClWorker
public class OrderNotifier { ... }

The behavior remains unchanged.

The architecture becomes explicit.

4️⃣ Structural Rules Are Enforced

Clprolf does not merely recommend architectural discipline.

It can enforce structural coherence.

Example:

@ClAgent
public class AnimalImpl extends AnimalWorker { }

This attempts to inherit from a class of a different nature.

This is considered as a violation by the ArchUnit checker.

The equivalent Java code would compile:

public class AnimalImpl extends AnimalWorker { }

Clprolf rejects it as architecturally inconsistent.

5️⃣ Structured Interfaces

Clprolf also introduces structured interface categories.

`family`

Represents an abstract family of related implementations.

@ClAgent
@ClFamily
public interface Animal {

    void eat(int quantity);

}

`trait`

Represents a capability shared across multiple families.

@ClAgent
@ClTrait
public interface Payable {

    void pay();

}

`free`

Represents a flexible interface without a predefined structural role.

@ClFree
public interface ExternalApi {
}

Unlike traditional interfaces, Clprolf interfaces participate in the structural model of the system.

6️⃣ What Clprolf Changes

Clprolf does not change:

algorithms,
execution flow,
runtime behavior.

Instead, it changes:

role visibility,
architectural clarity,
inheritance consistency,
structural guarantees.

7️⃣ Philosophy in One Sentence

Clprolf encodes architectural responsibility at the language level instead of leaving it entirely to convention.

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.

A Global Model of How Classes Relate to Each Other in Clprolf framework

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 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 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                       │
│        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 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

Introducing the ArchUnit Checker for the Clprolf Framework

What is Clprolf?

Bringing Architecture into the Build Process

Core Rules

A class cannot be both Agent and Worker

Inheritance must preserve the role

Family interfaces must match implementation roles

Trait interfaces may only extend other trait interfaces

Clprolf interfaces must declare a target role

Inheriting interfaces must have a role compatible with inherited traits

Family interfaces must have compatible inherited family interfaces

Direct trait implementation must respect trait roles

Optional Strict Validation

Every class should declare a Clprolf role

Every interface should declare a Clprolf role

Classes should not directly implement trait interfaces

Classes should implement only one primary family interface

Why It Matters

Clprolf — Official Documentation

Introduction

I) The Two Fundamental Principles

1. A class is either business-oriented or technical

Business / Domain World

Technical World

2. Inheritance must preserve the domain

II) Class Types

II.1) ClAgent

II.2) ClWorker

II.3) ClDraft

II.4) Primary Domain and Technical Code

II.5) Freedom of Interpretation and framework Recommendations

III) Inheritance

Valid Example

Discouraged Example

IV) Flexibility

V) Interfaces

V.1) ClFamily

Example

V.2) ClTrait

Business Example

Technical Example

V.3) ClFree

Example

V.4) Interface Usage

V.5) Note on Clprolf and the Interface Segregation Principle (ISP)

VI) General Architecture

VIII) Purpose of the framework

IX) ArchUnit Checker for the Clprolf Framework

clprolf_classes_must_not_mix_agent_and_worker

agent_worker_inheritance_must_not_mix

family_interface_role_must_match_implementation

(non-strict mode) trait_interface_role_must_match_direct_implementation

trait_interfaces_must_extend_only_trait_interfaces

clprolf_interfaces_must_have_target_role

inheriting_interface_role_must_match_trait_interface_target_role

family_interface_target_role_must_match_inherited_family_interface

Stricter Rules

optional_all_classes_should_have_clprolf_role

optional_all_interfaces_should_have_clprolf_role

optional_class_should_not_implement_trait_directly

optional_class_must_implement_only_one_family_interface

X) Clprolf and Existing Architectures

XI) Summary

Classes

Interfaces

Two Fundamental Rules

Clprolf — Quick Start

🎯 The Problem

💡 The Clprolf Approach

🧱 Class Roles

agent

worker

draft

🧠 Inheritance

🔗 Interfaces

⚖️ What Clprolf Provides

🎯 When to Use Clprolf

⚖️ Philosophy

🔚 In One Sentence

II.1) `ClAgent`

II.2) `ClWorker`

II.3) `ClDraft`

V.1) `ClFamily`

V.2) `ClTrait`

V.3) `ClFree`

`agent`

`worker`

`draft`

2️⃣ Starting Flexible with `draft`

`family`

`trait`

`free`

🎯 Business Responsibility → `agent`

⚙️ Technical Responsibilities → `worker`