Note: I used Antrophic Claude 4.5 Sonnet to generate the code examples in this document. Before, I feeded it with an article about Capability-Centric Architecture
INTRODUCTION: WHY YOU NEED A NEW ARCHITECTURAL APPROACH
Welcome to the world of Capability-Centric Architecture, a revolutionary architectural pattern that solves a problem you might not even know you have yet. If you have ever struggled with building systems that need to be both flexible and performant, that must evolve rapidly while maintaining stability, or that span the spectrum from embedded devices to cloud platforms, then this tutorial is for you.
Traditional architectural patterns force us into uncomfortable choices. Layered architectures work well for simple applications but become tangled messes as systems grow. Domain-Driven Design provides excellent domain modeling but struggles with hardware integration and real-time constraints. Clean Architecture offers beautiful separation of concerns but treats hardware as just another replaceable component, which simply does not work when your system must read sensor data every hundred microseconds.
Capability-Centric Architecture, or CCA for short, emerged from analyzing why these existing patterns fail when systems must evolve, integrate new technologies like artificial intelligence and containerization, or span from microcontrollers to cloud platforms. Instead of treating these as separate problems requiring separate solutions, CCA provides a unified conceptual framework with built-in mechanisms for managing complexity, dependencies, and change.
In this tutorial, we will build your understanding from the ground up. We will start with the core concepts, move through detailed implementation steps, and finish with real-world examples that demonstrate how CCA works in practice. By the end, you will understand not just what CCA is, but how to apply it to your own systems.
STEP ONE: UNDERSTANDING THE CAPABILITY NUCLEUS
The foundation of Capability-Centric Architecture is the Capability Nucleus. Think of a nucleus as a structured way to organize a cohesive piece of functionality that delivers value. Every capability in your system follows this same structural pattern, whether it controls a motor in an industrial robot or processes millions of payment transactions in a cloud platform.
The Capability Nucleus consists of three concentric layers, each with a distinct purpose and different rules about what it can depend on. Understanding these layers is crucial because they provide the separation of concerns that makes CCA so powerful.
The innermost layer is called the Essence. This layer contains pure domain logic or algorithmic core that defines what the capability does. For a temperature control capability, the Essence contains the control algorithm itself. For a payment processing capability, the Essence contains the business rules for validating and executing payments. The critical characteristic of the Essence is that it has no dependencies on anything outside itself except for capability contracts, which we will discuss shortly.
Let us look at a simple example to make this concrete. Imagine we are building a temperature control system. The Essence would look something like this:
public class TemperatureControlEssence {
private final ControlParameters parameters;
public TemperatureControlEssence(ControlParameters parameters) {
this.parameters = parameters;
}
public double calculateControl(double currentTemp, double targetTemp) {
double error = targetTemp - currentTemp;
double proportional = parameters.getKp() * error;
double integral = parameters.getKi() * accumulatedError;
double derivative = parameters.getKd() * (error - previousError);
double output = proportional + integral + derivative;
previousError = error;
accumulatedError += error;
return clamp(output, 0.0, 1.0);
}
private double clamp(double value, double min, double max) {
if (value < min) return min;
if (value > max) return max;
return value;
}
private double previousError = 0.0;
private double accumulatedError = 0.0;
}
Notice how this code contains pure logic with no external dependencies. There are no database calls, no hardware register reads, no network communication. This is intentional and powerful. Because the Essence has no infrastructure dependencies, you can test it in milliseconds without any setup. You can run thousands of test cases to verify the control algorithm works correctly under all conditions. You can even prove mathematical properties about the algorithm if needed.
The middle layer is called the Realization. This layer contains the necessary mechanisms to make the Essence work in the real world. For embedded systems, this includes hardware access, interrupt handlers, and direct memory access controllers. For enterprise systems, this includes database access, message queue integration, and API implementations. The Realization depends on both the Essence and the external technical infrastructure.
Continuing our temperature control example, the Realization might look like this:
public class TemperatureControlRealization {
private final TemperatureControlEssence essence;
private static final int TEMP_SENSOR_REGISTER = 0x40001000;
private static final int HEATER_CONTROL_REGISTER = 0x40002000;
public TemperatureControlRealization(TemperatureControlEssence essence) {
this.essence = essence;
}
public void initialize() {
configureSensor();
configureHeater();
}
public void controlLoop() {
double currentTemp = readTemperature();
double targetTemp = getTargetTemperature();
double controlOutput = essence.calculateControl(currentTemp, targetTemp);
setHeaterPower(controlOutput);
}
private double readTemperature() {
int rawValue = readRegisterDirect(TEMP_SENSOR_REGISTER);
return convertToTemperature(rawValue);
}
private void setHeaterPower(double power) {
int rawValue = convertToPWM(power);
writeRegisterDirect(HEATER_CONTROL_REGISTER, rawValue);
}
private native int readRegisterDirect(int address);
private native void writeRegisterDirect(int address, int value);
private void configureSensor() {
// Hardware-specific sensor configuration
}
private void configureHeater() {
// Hardware-specific heater configuration
}
private double convertToTemperature(int rawValue) {
return rawValue * 0.01;
}
private int convertToPWM(double power) {
return (int)(power * 255);
}
private double targetTemperature = 25.0;
private double getTargetTemperature() {
return targetTemperature;
}
}
The Realization bridges the gap between pure logic and physical reality. It handles all the messy details of hardware interaction while keeping the Essence clean and testable. Notice how the Realization uses the Essence by calling its calculateControl method, but adds all the infrastructure code needed to read sensors and control heaters.
The outermost layer is called the Adaptation. This layer provides the interfaces through which other capabilities interact with this capability and through which this capability interacts with external systems. Unlike traditional adapters which are often one-directional, Adaptations in CCA are bidirectional and can have different scopes depending on the needs of the capability.
For our temperature control example, the Adaptation provides a clean interface for other capabilities:
public class TemperatureControlAdaptation {
private final TemperatureControlRealization realization;
public TemperatureControlAdaptation(TemperatureControlRealization realization) {
this.realization = realization;
}
public void start() {
realization.initialize();
}
public void stop() {
// Cleanup and shutdown
}
public TemperatureStatus getStatus() {
return new TemperatureStatus(
realization.getCurrentTemperature(),
realization.getTargetTemperature(),
realization.isControlActive()
);
}
public void setTargetTemperature(double temperature) {
realization.setTargetTemperature(temperature);
}
}
The Adaptation provides a high-level interface that other capabilities can use without knowing anything about hardware registers or control algorithms. This separation allows each layer to evolve independently.
The key insight is that whether you are building an embedded temperature controller or an enterprise payment processor, the same structural pattern applies. The Essence contains pure domain logic. The Realization integrates with infrastructure, whether that is hardware registers or databases and message queues. The Adaptation provides interfaces for external interaction.
STEP TWO: DEFINING CAPABILITY CONTRACTS
Capabilities do not interact with each other through direct dependencies. Instead, they interact through Contracts. This is a fundamental principle of CCA that enables independent evolution and prevents the tangled dependency graphs that plague traditional architectures.
A Capability Contract consists of three parts. The Provision declares what the capability offers to others. The Requirement declares what the capability needs from others. The Protocol defines the supported interaction patterns and quality attributes.
Let us define a contract for our temperature monitoring capability:
public interface TemperatureMonitoringContract {
interface Provision {
void subscribeToTemperature(TemperatureSubscriber subscriber, int updateRateHz);
double getCurrentTemperature();
TemperatureHistory getHistory(Timestamp startTime, Timestamp endTime);
}
interface Requirement {
CalibrationParameters getCalibration(String sensorId);
void onCalibrationChange(CalibrationChangeListener listener);
}
interface Protocol {
int MAX_LATENCY_MS = 10;
int MIN_UPDATE_RATE_HZ = 1;
int MAX_UPDATE_RATE_HZ = 1000;
enum InteractionPattern {
SYNCHRONOUS_QUERY,
ASYNCHRONOUS_SUBSCRIBE,
BATCH_QUERY
}
}
}
This contract explicitly states what the temperature monitoring capability provides to other capabilities. It can deliver temperature updates through subscriptions, provide current readings on demand, and return historical data. The contract also states what this capability needs from others, specifically calibration data from a calibration management capability. Finally, the protocol section defines quality attributes like maximum latency and supported update rates, plus the interaction patterns that consumers can use.
Contracts enable capabilities to evolve independently. As long as a capability continues to fulfill its contract, its internal implementation can change without affecting other capabilities. This is similar to interface-based programming, but contracts are richer. They include quality attributes, interaction patterns, and both provisions and requirements.
The power of contracts becomes clear when you consider evolution. Suppose we want to improve our temperature monitoring capability by adding a new machine learning-based anomaly detection feature. We can add this to the Provision interface as a new method:
interface Provision {
void subscribeToTemperature(TemperatureSubscriber subscriber, int updateRateHz);
double getCurrentTemperature();
TemperatureHistory getHistory(Timestamp startTime, Timestamp endTime);
AnomalyReport detectAnomalies(Timestamp startTime, Timestamp endTime);
}
Existing consumers of the contract continue to work without any changes because we only added a new method. This is backward compatible evolution. Consumers that want to use the new anomaly detection feature can start calling the new method when they are ready.
STEP THREE: IMPLEMENTING EFFICIENCY GRADIENTS
One of the most innovative aspects of CCA is the concept of Efficiency Gradients. This addresses a fundamental challenge in building systems that span from embedded to enterprise domains. Some operations must execute with minimal overhead, direct hardware access, and predictable timing. Other operations can tolerate more abstraction in exchange for flexibility and maintainability.
An Efficiency Gradient allows different parts of the system to operate at different levels of abstraction and optimization. Critical paths can use direct hardware access with minimal indirection. Less critical paths can use higher abstractions and more flexible implementations.
Consider a data acquisition system that reads multiple sensors. The sensor reading itself must be fast and deterministic. The data processing can be more flexible. The data storage can be even more abstract. Let us see how this works in code:
public class DataAcquisitionCapability {
private static final int SENSOR_BASE_ADDRESS = 0x40000000;
private static final int SENSOR_COUNT = 8;
public void sensorInterruptHandler() {
for (int i = 0; i < SENSOR_COUNT; i++) {
int rawValue = readRegisterDirect(SENSOR_BASE_ADDRESS + (i * 4));
sensorBuffer[i] = rawValue;
}
dataReady = true;
}
public void processData() {
if (!dataReady) return;
SensorReading[] readings = new SensorReading[SENSOR_COUNT];
for (int i = 0; i < SENSOR_COUNT; i++) {
readings[i] = new SensorReading(
i,
convertToPhysicalValue(sensorBuffer[i]),
System.currentTimeMillis()
);
}
SensorReading[] filtered = applyFiltering(readings);
storageQueue.add(filtered);
dataReady = false;
}
public void storeData() {
List<SensorReading[]> batch = new ArrayList<>();
storageQueue.drainTo(batch);
if (batch.isEmpty()) return;
storage.beginTransaction();
try {
for (SensorReading[] readings : batch) {
for (SensorReading reading : readings) {
storage.insert(reading);
}
}
storage.commit();
analytics.processNewData(batch);
} catch (Exception e) {
storage.rollback();
}
}
private int[] sensorBuffer = new int[SENSOR_COUNT];
private volatile boolean dataReady = false;
private Queue<SensorReading[]> storageQueue = new ConcurrentLinkedQueue<>();
private native int readRegisterDirect(int address);
private double convertToPhysicalValue(int rawValue) {
return rawValue * 0.001;
}
private SensorReading[] applyFiltering(SensorReading[] readings) {
// Apply filtering algorithms
return readings;
}
}
Notice the three different efficiency gradients in this code. The sensorInterruptHandler runs at the highest efficiency gradient. It executes in interrupt context with minimal overhead, using direct register reads and a simple array for buffering. No object allocation, no abstractions, just raw performance.
The processData method runs at a medium efficiency gradient. It uses object-oriented design with SensorReading objects, applies filtering algorithms, and uses a concurrent queue for buffering. This is more flexible and maintainable than the interrupt handler, but still reasonably efficient.
The storeData method runs at the lowest efficiency gradient, meaning highest abstraction. It uses database transactions, batch processing, and triggers analytics. This is the most flexible layer where we can easily change storage mechanisms or add new analytics without affecting the critical real-time paths.
This gradient approach is crucial for embedded systems where you must balance real-time performance requirements with software engineering best practices. It is equally valuable for enterprise systems where you want to optimize high-traffic request paths while using more flexible implementations for administrative operations.
STEP FOUR: MANAGING EVOLUTION WITH EVOLUTION ENVELOPES
Systems evolve. Requirements change. Technologies advance. New features get added. Old features get deprecated. Traditional architectures handle this through informal processes and hope that changes do not break things. CCA makes evolution explicit and manageable through Evolution Envelopes.
An Evolution Envelope defines how a capability can change over time while maintaining compatibility with other capabilities. It specifies what can change, what must remain stable, and how changes are communicated. Every capability has an Evolution Envelope that includes version information, deprecation policies, and migration paths.
Here is what an Evolution Envelope looks like:
public class EvolutionEnvelope {
private final String capabilityName;
private final Version currentVersion;
private final List<Version> supportedVersions;
private final DeprecationPolicy deprecationPolicy;
private final MigrationGuide migrationGuide;
public boolean isCompatible(Version requiredVersion) {
if (requiredVersion.getMajor() != currentVersion.getMajor()) {
return supportedVersions.contains(requiredVersion);
}
return currentVersion.getMinor() >= requiredVersion.getMinor();
}
public List<MigrationStep> getMigrationPath(Version fromVersion) {
return migrationGuide.getPath(fromVersion, currentVersion);
}
public DeprecationInfo getDeprecationInfo(String featureName) {
return deprecationPolicy.getDeprecationInfo(featureName);
}
}
The Evolution Envelope uses semantic versioning with major, minor, and patch version numbers. Patch versions are always compatible and contain only bug fixes. Minor versions add new features while maintaining backward compatibility. Major versions can break compatibility but should be rare and well-planned.
When you need to make a breaking change to a contract, you introduce it as a new major version and maintain the old version for a transition period. The Evolution Envelope documents this transition, provides migration paths, and specifies deprecation policies.
For example, suppose we want to change our temperature monitoring contract to use a more efficient data structure. We would create version two of the contract with the new structure, mark the old methods as deprecated in version one point five, provide a migration tool to help consumers update their code, and document a six-month transition period before removing version one support entirely.
This formal approach to evolution prevents the chaos that often accompanies system changes. Consumers know exactly what is changing, when it will change, and how to adapt. Providers can evolve their implementations without breaking existing consumers.
STEP FIVE: BUILDING A COMPLETE CAPABILITY
Now that we understand the core concepts, let us build a complete capability from scratch. We will create a notification capability that can send alerts and messages through multiple channels like email, SMS, and push notifications. This example will demonstrate all the key aspects of CCA implementation.
First, we define the contract:
public interface NotificationContract {
NotificationResult sendNotification(Notification notification);
List<NotificationResult> sendBatch(List<Notification> notifications);
DeliveryStatus getStatus(String notificationId);
void cancelNotification(String notificationId);
}
This contract is simple and focused. It provides methods to send individual notifications, send batches for efficiency, check delivery status, and cancel pending notifications. Notice that the contract does not specify how notifications are sent, what infrastructure is used, or how the capability is implemented. It only defines what the capability provides.
Next, we implement the Essence layer with pure business logic:
public class NotificationEssence {
public ValidationResult validateNotification(Notification notification) {
ValidationResult result = new ValidationResult();
if (notification.getRecipient() == null || notification.getRecipient().isEmpty()) {
result.addError("Recipient is required");
}
if (notification.getMessage() == null || notification.getMessage().isEmpty()) {
result.addError("Message is required");
}
if (notification.getChannel() == NotificationChannel.SMS) {
if (notification.getMessage().length() > 160) {
result.addError("SMS messages cannot exceed 160 characters");
}
}
if (notification.getChannel() == NotificationChannel.EMAIL) {
if (!isValidEmail(notification.getRecipient())) {
result.addError("Invalid email address format");
}
}
return result;
}
public Priority calculatePriority(Notification notification) {
if (notification.getType() == NotificationType.ALERT) {
return Priority.HIGH;
}
if (notification.getType() == NotificationType.REMINDER) {
return Priority.MEDIUM;
}
return Priority.LOW;
}
private boolean isValidEmail(String email) {
return email.contains("@") && email.contains(".");
}
}
The Essence contains pure validation logic and priority calculation. There are no infrastructure dependencies, no database calls, no external service invocations. This makes it trivially easy to test. We can write hundreds of test cases that execute in milliseconds to verify all the business rules work correctly.
Now we implement the Realization layer that integrates with infrastructure:
public class NotificationRealization {
private final NotificationEssence essence;
private final EmailService emailService;
private final SMSService smsService;
private final PushNotificationService pushService;
private final NotificationQueue queue;
private final NotificationRepository repository;
public NotificationRealization(
NotificationEssence essence,
EmailService emailService,
SMSService smsService,
PushNotificationService pushService,
NotificationQueue queue,
NotificationRepository repository
) {
this.essence = essence;
this.emailService = emailService;
this.smsService = smsService;
this.pushService = pushService;
this.queue = queue;
this.repository = repository;
}
public NotificationResult send(Notification notification) {
ValidationResult validation = essence.validateNotification(notification);
if (!validation.isValid()) {
return NotificationResult.validationFailure(validation.getErrors());
}
Priority priority = essence.calculatePriority(notification);
String notificationId = generateId();
notification.setId(notificationId);
repository.save(notification);
if (priority == Priority.HIGH) {
return sendImmediately(notification);
} else {
queue.enqueue(notification);
return NotificationResult.queued(notificationId);
}
}
private NotificationResult sendImmediately(Notification notification) {
try {
switch (notification.getChannel()) {
case EMAIL:
emailService.send(
notification.getRecipient(),
notification.getSubject(),
notification.getMessage()
);
break;
case SMS:
smsService.send(
notification.getRecipient(),
notification.getMessage()
);
break;
case PUSH:
pushService.send(
notification.getRecipient(),
notification.getMessage()
);
break;
}
repository.updateStatus(notification.getId(), DeliveryStatus.SENT);
return NotificationResult.success(notification.getId());
} catch (Exception e) {
repository.updateStatus(notification.getId(), DeliveryStatus.FAILED);
return NotificationResult.failure(notification.getId(), e.getMessage());
}
}
public List<NotificationResult> sendBatch(List<Notification> notifications) {
Map<NotificationChannel, List<Notification>> grouped = groupByChannel(notifications);
List<NotificationResult> results = new ArrayList<>();
for (Map.Entry<NotificationChannel, List<Notification>> entry : grouped.entrySet()) {
results.addAll(sendBatchThroughChannel(entry.getKey(), entry.getValue()));
}
return results;
}
private Map<NotificationChannel, List<Notification>> groupByChannel(
List<Notification> notifications
) {
Map<NotificationChannel, List<Notification>> grouped = new HashMap<>();
for (Notification notification : notifications) {
grouped.computeIfAbsent(
notification.getChannel(),
k -> new ArrayList<>()
).add(notification);
}
return grouped;
}
private List<NotificationResult> sendBatchThroughChannel(
NotificationChannel channel,
List<Notification> notifications
) {
// Channel-specific batch sending logic
return new ArrayList<>();
}
private String generateId() {
return "NOTIF-" + System.currentTimeMillis();
}
}
The Realization brings together the Essence and all the infrastructure services. It uses the Essence for validation and priority calculation, then handles all the messy details of actually sending notifications through various channels, managing queues, and updating the repository.
Next, we implement the Adaptation layer:
public class NotificationAdaptation {
private final NotificationRealization realization;
public NotificationAdaptation(NotificationRealization realization) {
this.realization = realization;
}
public HttpResponse handleNotificationRequest(HttpRequest request) {
try {
Notification notification = parseNotification(request);
NotificationResult result = realization.send(notification);
if (result.isSuccessful()) {
return HttpResponse.ok(serializeResult(result));
} else {
return HttpResponse.badRequest(result.getErrorMessage());
}
} catch (Exception e) {
return HttpResponse.internalServerError(e.getMessage());
}
}
public void handleNotificationMessage(Message message) {
Notification notification = deserializeNotification(message.getBody());
realization.send(notification);
}
private Notification parseNotification(HttpRequest request) {
// Parse JSON or XML from HTTP request body
return new Notification();
}
private Notification deserializeNotification(byte[] body) {
// Deserialize from message format
return new Notification();
}
private String serializeResult(NotificationResult result) {
// Serialize to JSON or XML
return "{}";
}
}
The Adaptation provides multiple interfaces for accessing the capability. It can handle HTTP requests for synchronous notification sending, or it can consume messages from a queue for asynchronous processing. This flexibility allows the same capability to be used in different contexts without changing its core implementation.
Finally, we bring it all together in the complete capability:
public class NotificationCapability implements CapabilityInstance {
private final NotificationEssence essence;
private final NotificationRealization realization;
private final NotificationAdaptation adaptation;
private final EvolutionEnvelope evolutionEnvelope;
public NotificationCapability(
EmailService emailService,
SMSService smsService,
PushNotificationService pushService,
NotificationQueue queue,
NotificationRepository repository
) {
this.essence = new NotificationEssence();
this.realization = new NotificationRealization(
essence,
emailService,
smsService,
pushService,
queue,
repository
);
this.adaptation = new NotificationAdaptation(realization);
this.evolutionEnvelope = createEvolutionEnvelope();
}
public void initialize() {
// Initialize infrastructure services
}
public void start() {
// Start message queue consumer
// Start retry processor
}
public void stop() {
// Stop consumers
// Flush queues
}
public Object getContractImplementation(Class<?> contractType) {
if (contractType == NotificationContract.class) {
return new NotificationContractImpl(realization);
}
return null;
}
public void injectDependency(Class<?> contractType, Object implementation) {
// This capability has no dependencies
}
public EvolutionEnvelope getEvolutionEnvelope() {
return evolutionEnvelope;
}
private EvolutionEnvelope createEvolutionEnvelope() {
return new EvolutionEnvelope(
"NotificationCapability",
new Version(1, 0, 0),
Arrays.asList(new Version(1, 0, 0)),
new DeprecationPolicy(),
new MigrationGuide()
);
}
}
This complete example demonstrates all the key aspects of implementing a capability. The contract defines what the capability provides. The Essence contains pure business logic. The Realization integrates infrastructure. The Adaptation provides external interfaces. The capability ties everything together and manages the lifecycle.
STEP SIX: INJECTING DEPENDENCIES BETWEEN CAPABILITIES
Capabilities rarely work in isolation. They need services from other capabilities. In CCA, these dependencies are managed through a mechanism called dependency injection based on contracts. This is fundamentally different from traditional dependency injection because it operates at the capability level and uses contracts rather than concrete implementations.
The process works through a Capability Registry that manages all capabilities and their interactions. When a capability needs something from another capability, it declares this need in its contract requirements. The registry then binds the consumer to a provider that fulfills that contract.
Let us see how this works with a concrete example. Suppose our notification capability needs to look up user preferences to determine the best channel for each user. We would first define the contract requirement:
public interface NotificationContract {
interface Requirement {
UserPreferences getUserPreferences(String userId);
}
}
Then in our capability implementation, we add a field to hold the injected dependency:
public class NotificationCapability implements CapabilityInstance {
private final NotificationEssence essence;
private final NotificationRealization realization;
private final NotificationAdaptation adaptation;
private UserPreferencesContract userPreferences;
public void injectDependency(Class<?> contractType, Object implementation) {
if (contractType == UserPreferencesContract.class) {
this.userPreferences = (UserPreferencesContract) implementation;
}
}
}
The Capability Registry handles the actual injection. It maintains a dependency graph of all capabilities and their requirements. When initializing the system, it performs a topological sort to determine the correct initialization order, ensuring that capabilities are initialized before any capabilities that depend on them.
Here is how the registry manages this:
public class CapabilityRegistry {
private final Map<String, CapabilityDescriptor> capabilities;
private final Map<String, List<ContractBinding>> bindings;
private final DependencyResolver resolver;
public void bindCapabilities(
String consumer,
String provider,
Class<?> contractType
) {
CapabilityDescriptor consumerDesc = capabilities.get(consumer);
CapabilityDescriptor providerDesc = capabilities.get(provider);
if (!providerDesc.provides(contractType)) {
throw new IllegalArgumentException(
provider + " does not provide " + contractType.getName()
);
}
if (!consumerDesc.requires(contractType)) {
throw new IllegalArgumentException(
consumer + " does not require " + contractType.getName()
);
}
if (resolver.wouldCreateCycle(consumer, provider)) {
throw new CircularDependencyException(
"Binding would create circular dependency"
);
}
ContractBinding binding = new ContractBinding(
consumerDesc,
providerDesc,
contractType
);
bindings.computeIfAbsent(consumer, k -> new ArrayList<>()).add(binding);
resolver.addDependency(consumer, provider);
}
public List<String> getInitializationOrder() {
return resolver.topologicalSort();
}
}
The registry prevents circular dependencies by checking the dependency graph before creating bindings. If a binding would create a cycle, the registry rejects it and forces you to restructure your capabilities. This is one of the key mechanisms for avoiding architectural antipatterns.
The Lifecycle Manager uses the registry to initialize capabilities in the correct order:
public class CapabilityLifecycleManager {
private final CapabilityRegistry registry;
private final Map<String, CapabilityInstance> instances;
public void initializeAll() {
List<String> initOrder = registry.getInitializationOrder();
for (String capabilityName : initOrder) {
initializeCapability(capabilityName);
}
}
public void initializeCapability(String capabilityName) {
CapabilityDescriptor descriptor = registry.getCapability(capabilityName);
CapabilityInstance instance = createInstance(descriptor);
injectDependencies(instance, capabilityName);
instance.initialize();
instances.put(capabilityName, instance);
if (descriptor.isAutoStart()) {
instance.start();
}
}
private void injectDependencies(CapabilityInstance instance, String capabilityName) {
List<ContractBinding> capabilityBindings = registry.getBindings(capabilityName);
for (ContractBinding binding : capabilityBindings) {
CapabilityInstance provider = instances.get(binding.getProviderName());
if (provider == null) {
throw new DependencyNotAvailableException(
capabilityName + " requires " + binding.getProviderName() +
" but it is not initialized"
);
}
Object contractImpl = provider.getContractImplementation(binding.getContractType());
instance.injectDependency(binding.getContractType(), contractImpl);
}
}
private CapabilityInstance createInstance(CapabilityDescriptor descriptor) {
try {
Class<?> capabilityClass = Class.forName(descriptor.getImplementationClass());
return (CapabilityInstance) capabilityClass.getDeclaredConstructor().newInstance();
} catch (Exception e) {
throw new CapabilityInstantiationException(
"Failed to create instance of " + descriptor.getName(),
e
);
}
}
}
This dependency injection mechanism ensures that capabilities are properly initialized with all their dependencies before they start executing. It eliminates a common source of initialization bugs where components try to use dependencies that are not yet available.
STEP SEVEN: TESTING YOUR CAPABILITIES
Testing is where the layered structure of CCA really shines. The separation of Essence, Realization, and Adaptation allows different testing strategies for different parts of the capability.
The Essence can be tested with pure unit tests that require no infrastructure. Because the Essence has no external dependencies, tests are fast, deterministic, and easy to write. Let us look at tests for our notification Essence:
public class NotificationEssenceTest {
private NotificationEssence essence;
public void setUp() {
essence = new NotificationEssence();
}
public void testValidateNotification_ValidNotification_ReturnsValid() {
Notification notification = new Notification();
notification.setRecipient("user@example.com");
notification.setMessage("Test message");
notification.setChannel(NotificationChannel.EMAIL);
ValidationResult result = essence.validateNotification(notification);
assertTrue(result.isValid());
assertEquals(0, result.getErrors().size());
}
public void testValidateNotification_MissingRecipient_ReturnsInvalid() {
Notification notification = new Notification();
notification.setMessage("Test message");
notification.setChannel(NotificationChannel.EMAIL);
ValidationResult result = essence.validateNotification(notification);
assertFalse(result.isValid());
assertTrue(result.getErrors().contains("Recipient is required"));
}
public void testValidateNotification_SMSTooLong_ReturnsInvalid() {
Notification notification = new Notification();
notification.setRecipient("+1234567890");
notification.setMessage("This message is way too long for SMS and exceeds the one hundred sixty character limit that is enforced by the validation logic in the essence layer");
notification.setChannel(NotificationChannel.SMS);
ValidationResult result = essence.validateNotification(notification);
assertFalse(result.isValid());
assertTrue(result.getErrors().contains("SMS messages cannot exceed 160 characters"));
}
public void testCalculatePriority_AlertType_ReturnsHigh() {
Notification notification = new Notification();
notification.setType(NotificationType.ALERT);
Priority priority = essence.calculatePriority(notification);
assertEquals(Priority.HIGH, priority);
}
}
These tests run in milliseconds and provide complete coverage of the business logic. You can run thousands of them as part of your continuous integration pipeline without any performance impact.
The Realization requires integration tests that verify infrastructure interaction. However, we can use mocks to avoid depending on actual infrastructure:
public class NotificationRealizationTest {
private NotificationEssence essence;
private EmailService mockEmailService;
private SMSService mockSMSService;
private NotificationRepository mockRepository;
private NotificationRealization realization;
public void setUp() {
essence = new NotificationEssence();
mockEmailService = mock(EmailService.class);
mockSMSService = mock(SMSService.class);
mockRepository = mock(NotificationRepository.class);
realization = new NotificationRealization(
essence,
mockEmailService,
mockSMSService,
mock(PushNotificationService.class),
mock(NotificationQueue.class),
mockRepository
);
}
public void testSend_ValidEmailNotification_CallsEmailService() {
Notification notification = new Notification();
notification.setRecipient("user@example.com");
notification.setMessage("Test message");
notification.setChannel(NotificationChannel.EMAIL);
notification.setType(NotificationType.ALERT);
NotificationResult result = realization.send(notification);
assertTrue(result.isSuccessful());
verify(mockEmailService).send(
eq("user@example.com"),
anyString(),
eq("Test message")
);
verify(mockRepository).save(notification);
}
public void testSend_EmailServiceFails_ReturnsFailure() {
Notification notification = new Notification();
notification.setRecipient("user@example.com");
notification.setMessage("Test message");
notification.setChannel(NotificationChannel.EMAIL);
notification.setType(NotificationType.ALERT);
when(mockEmailService.send(anyString(), anyString(), anyString()))
.thenThrow(new EmailServiceException("Service unavailable"));
NotificationResult result = realization.send(notification);
assertFalse(result.isSuccessful());
verify(mockRepository).updateStatus(anyString(), eq(DeliveryStatus.FAILED));
}
}
These tests verify that the Realization correctly integrates with infrastructure services. They run in seconds rather than milliseconds because of the mocking overhead, but they still do not require actual infrastructure to be running.
Contract tests verify that capabilities correctly implement their contracts:
public class NotificationContractTest {
private NotificationContract contract;
public void setUp() {
NotificationCapability capability = createTestCapability();
contract = (NotificationContract) capability.getContractImplementation(
NotificationContract.class
);
}
public void testContract_SendNotification_ReturnsResult() {
Notification notification = createValidNotification();
NotificationResult result = contract.sendNotification(notification);
assertNotNull(result);
}
public void testContract_SendBatch_ReturnsResultsForAll() {
List<Notification> notifications = Arrays.asList(
createValidNotification(),
createValidNotification(),
createValidNotification()
);
List<NotificationResult> results = contract.sendBatch(notifications);
assertEquals(notifications.size(), results.size());
}
private NotificationCapability createTestCapability() {
return new NotificationCapability(
new TestEmailService(),
new TestSMSService(),
new TestPushService(),
new TestNotificationQueue(),
new TestNotificationRepository()
);
}
private Notification createValidNotification() {
Notification notification = new Notification();
notification.setRecipient("test@example.com");
notification.setMessage("Test message");
notification.setChannel(NotificationChannel.EMAIL);
return notification;
}
}
These testing strategies provide comprehensive coverage while keeping tests fast and maintainable. The Essence tests are pure unit tests that run in milliseconds. The Realization tests use mocks to verify infrastructure integration. Contract tests ensure that capabilities fulfill their promises.
CONCLUSION: PUTTING IT ALL TOGETHER
Capability-Centric Architecture provides a unified architectural pattern that works equally well for embedded and enterprise systems. By organizing systems around capabilities structured as nuclei with Essence, Realization, and Adaptation layers, software engineers achieve a separation of concerns that enables independent evolution, testing, and deployment.
The pattern addresses fundamental architectural challenges that have plagued software development for decades. Circular dependencies are prevented through contract-based interaction and dependency graph management. Technology dependencies are isolated in the Realization layer, allowing technologies to be replaced without affecting business logic. Quality attributes are addressed explicitly through contracts and efficiency gradients.
For embedded systems, efficiency gradients allow critical paths to use direct hardware access while non-critical paths use higher abstractions. This balances real-time performance requirements with software engineering best practices. Resource contracts make resource usage explicit and manageable.
For enterprise systems, contract-based interaction enables independent deployment and scaling of capabilities. Evolution envelopes provide a formal mechanism for managing change over time. Support for modern technologies like artificial intelligence, big data, and containerization is built into the architecture rather than added as an afterthought.
The architecture is practical to implement. Capabilities follow a clear structure that developers can consistently understand and apply. Testing strategies leverage the separation of Essence, Realization, and Adaptation to provide comprehensive coverage with fast, maintainable tests. Deployment flexibility allows the same capability code to run in different environments, from embedded devices to cloud platforms.
By following the principles outlined in this tutorial, you can build systems that are easier to understand, test, deploy, and evolve over time, whether those systems control industrial machinery, process billions of transactions, or anything in between.
No comments:
Post a Comment