Common pitfalls in enterprise class structure

The most common mistake is placing application-specific classes, such as Work- and Data-, in the organization layer because they might be reused later. This practice pollutes the enterprise layer, introduces unwanted dependencies, and makes the application portfolio fragile.

As a best practice, place assets in the organization layer only if they are genuinely used across multiple, distinct applications. Examples include employee data, a security model, or enterprise branding. If an asset is not universal, place it in a lower layer.

Example 1: The common data dumping ground

A frequent pitfall is creating a monolithic common data class, often named YourOrg-Data-Common. This anti-pattern begins with the intention to centralize properties, such as.Status, .ID, or .StartDate. Over time, the class becomes a disorganized repository that mixes unrelated data from different business domains. For example, a .TransactionID from a payment application stored alongside a .PolicyNumber from an insurance system.

Impact

This approach creates long-term issues that affect both performance and maintainability:

• Bloated data objects degrade performance.
• High risk of naming collisions creates logic conflicts between applications.

Correct approach

Create distinct, purposeful data classes such as YourOrg-Data-Policy or YourOrg-Data-Transaction that own their specific properties. This approach supports a decoupled, maintainable, and reusable Data Model.

Example 2: The monolithic base Case

Another common anti-pattern is the monolithic base Case. This occurs when the primary Case Type of an organization’s first major application is placed at the Enterprise layer to serve as a universal parent for all future work. For example, defining an Order Management Case Type as YourOrg-Work-Process forces unrelated processes, such as HR Onboarding, into an illogical inheritance structure.

Impact

This design introduces long-term complexity and maintenance challenges. Key impacts include:

• Developers waste effort hiding or overriding irrelevant features.
• The parent class becomes bloated with conditional logic, making maintenance difficult.

Correct approach

Keep Case Types within their own application or framework layers. Achieve reuse by identifying generic features, such as a standard Approval Subprocess, and factoring them into discrete, reusable modules.

Creating a Framework layer for a single application “just in case” it needs specialization is over-engineering. Most standard enterprise applications follow the rule of three: do not create a framework until you have at least three distinct implementations that need to share its components. A framework adds maintenance overhead and complexity that is not justified for a single application.

The pitfall of premature frameworking stems from designing for future reuse from day one. For example, an architect building a new Order Management application immediately creates a dedicated framework layer (for example, YourOrg-OrderingFW-Work-Order) based on speculation that different business units, such as Retail and Wholesale, might require distinct versions in the future. While this forward-thinking seems commendable, it imposes structural complexity before the business justification has been validated.

Impact

Premature Frameworking introduces unnecessary complexity and violates agile principles:

• Unnecessary complexity and maintenance overhead with no immediate return.
• Developers must manage rules across both the implementation and framework layers, making the application harder to navigate and increasing the cognitive load for Rule resolution.
• Violates the agile principle of “You Are Not Gonna Need It” (YAGNI) by investing effort in an abstraction that is speculative.

Correct approach

Follow the rule of three: build the first application cleanly in its own implementation layer. Only when a clear, validated need for a second or third distinct implementation arises should you refactor common, reusable components into a shared Framework layer. This approach ensures that abstractions are based on real, proven needs, not speculation.

The process-first design pitfall occurs when development is driven by the sequence of steps in a case type (Work- class) before the underlying business objects (Data- classes) are properly identified and modeled.

For example, a team building a Loan Application Case might immediately add properties such as ApplicantFirstName, ApplicantLastName, and LoanAmount directly to the Case Type because they are required for the user interface. This approach feels expedient because it serves the immediate needs of the process, but it overlooks the creation of a canonical, reusable Data Model that should exist independently of any single process.

Impact

This methodology inevitably leads to severe data integrity problems:

• Creation of information silos and data duplication across the enterprise.
• Lack of a single source of truth, causing maintenance issues when data needs updates.

Correct approach

Adopt a data-first approach. Identify core business nouns (for example, Customer, Loan, or Collateral) and define them as robust Data- classes at the appropriate enterprise layer. Then design Work- classes to orchestrate processes that act upon these stable, reusable Data Objects. This approach ensures a scalable and maintainable foundation.

A common but misguided approach is to treat the ECS as a glorified folder system for organizing rules. In this scenario, developers use the class hierarchy simply to group related assets (for example, placing all Rules for a claims application in a MyOrg-ClaimsApp class) without considering inheritance or specialization.

They view hyphenated class names as a naming convention for logical containers rather than as a mechanism for building a layered, reusable architecture. This superficial use of ECS misses its primary strategic purpose.

Impact

Ignoring ECS inheritance undermines scalability and reuse:

• Failure to use patterns and directed inheritance results in a flat, monolithic application with minimal or no reusability.
• Makes it impossible to implement the Situational Layer Cake™ because there is no structural foundation for creating specialized versions of the application for different regions, products, or channels.

Correct approach

View ECS as an engine for inheritance. Design the class structure to mirror business dimensions by allowing common Rules to reside in base classes and then be extended or overridden in specific layers. This approach unlocks the Pega core value of governed, scalable reuse.

The pitfall of monolithic implementation occurs when an entire application is built within a single, self-contained implementation layer, with no separation of concerns between enterprise-level assets and application-specific logic.

This often happens under pressure to deliver the first project quickly, leading teams to build everything, including core Data Models, integration connectors, and business logic, directly into one application Ruleset. For example, a Customer Data Model is defined as YourOrg-OrderingApp-Data-Customer, effectively trapping a fundamental business object inside the silo of a single application.

Impact

Monolithic implementation accelerates initial delivery but creates long-term technical debt:

• Accelerates initial delivery but creates significant technical debt.
• Undermines enterprise reuse principles.
• Forces future projects to either duplicate work or create fragile dependencies on the first application.

Correct approach

Practice separation of concerns from the start. Identify reusable assets and elevate them to the appropriate enterprise layer. This approach ensures that each new application builds on, rather than duplicates, the assets of the last. The Lead System Architect must have the foresight to design for scalability and reuse.

Check your knowledge with the following interaction: