C4 should be the de-facto diagramming style for SAFe Agile Teams

Intro

Let me first start with how I wrote this, because it's important. In my career I have crafted several architectural decisions. The most challenging presentations are when I have had to address both technical and business audiences. Technical story telling is an essential skill. As the Senior Director of IT Strategy and Architecture, I applied the "Pyramid Principle" extensively. You start with the answer, then state the why, how, and next steps. Usually, presenters don't do this. Instead they "build up" to the answer. Meanwhile, their audience has "lost the plot". Ever since I adapted this communication style, effectiveness of my communication has been lauded.

The Answer

Pilot C4 Diagramming Standard for the next PI (Planning Increment).

To deliver software that is timely, high-quality, and aligned with business goals, you should adopt the C4 diagramming style as the standard for visualizing architecture. C4 provides a clear, layered way to represent systems that works for executives, architects, and developers alike.

The Why

Executive Perspective

(a) Shared Understanding Across Audiences

C4 diagrams scale from high-level context (business view) to technical detail (developer view), ensuring everyone. From stakeholders to engineers everyone can interpret the architecture without the need for heavy tooling. Just enough design facilitates acceleration of the solution.

(b) Agility with Discipline

Unlike heavyweight modeling approaches, C4 is lightweight and iterative, making it compatible with agile teams while still ensuring design intent is explicit.

(c) Risk Mitigation 

Consistent visual models surface integration, security, and scalability risks early, reducing costly redesigns.

Practitioner Perspective

(a) Clarity of Scope and Boundaries

Context and container diagrams make dependencies, APIs, and infrastructure responsibilities unambiguous.

(b) Scalability and Deployment Readiness

Component and container views map directly to runtime environments, cloud services, and CI/CD pipelines.

(c) Knowledge Retention

C4 diagrams are simple enough to maintain as living documentation, reducing reliance on tribal knowledge.

The How

Like Google Maps, C4 lets you zoom in and out: executives see the “city map” (context), architects see the “neighborhood layout” (containers), and developers see the “street-level details” (components and code).

Leading organizations and open-source communities use C4 to replace ad-hoc diagrams with a consistent, widely understood notation.

Practitioner Example:

1. Context Diagram: Shows how the system interacts with users and external systems.
2. 
   Container Diagram: Breaks down major applications, services, and databases.
3. Component Diagram: Details the internals of each container and key responsibilities.
4. Code Diagram: Optional, zooming into classes, libraries, or modules for critical areas.

Practically, Context and container diagrams should be developed and maintained. The component and code diagrams usually have diminished return on time investment.

Leading Indicators

Business Outcomes

• Reduced communication gaps between business and IT.
• Faster alignment on architectural decisions, accelerating time-to-market.
• Lower risk of rework by ensuring shared understanding upfront.

Technical Outcomes

• Consistent, lightweight architecture diagrams across teams.
• Easier onboarding for new developers and faster knowledge transfer.
• Clear alignment between architecture, infrastructure, and code.

Decision

• Decide to adopt C4 as the standard architecture visualization method across projects.
• Provide teams with starter templates and simple guidance.
• Pilot the C4 approach in the next project increment and review effectiveness with both stakeholders and developers.

Conclusion

You can steal this, customize it and use it for your company. Good luck!!

Software Architectures need to be evaluated.

What constitutes an architecture?

“You employ stone, wood and concrete, and with these materials you build houses and palaces. That is construction. Ingenuity is at work.

But suddenly you touch my heart, you do me good, I am happy and I say ‘This is beautiful’. That is Architecture.”

- Le Corbusier, 1923

- Quoted in Architecture: From Prehistory to Post-modernism

Well, then what is software architecture?

There is no universal agreed upon formal definition of software architecture, however, the Software Engineering Institute (SEI) has defined it as follows:

“The software architecture of a system is the structure of structures of the system, which comprise software components, the externally visible properties of those components and the relationships among them.” - SEI’s definition of Software Architecture.

- It is a vehicle for communication among stakeholders.

- It is the manifestation of the earliest design decisions.

- It is a reusable, transferable abstraction.

Software elements – modules, components etc. Externally visible properties – does provide for internal flexibility. E.g. a contract is externally visible.

All designs involve tradeoffs. Architecture is the earliest life-cycle artifact that embodies significant design decisions: choices and tradeoffs.

Predict a system’s quality attributes by studying its architecture. We can analyze architecture for achievement of quality attributes – it determines risk not a “grade”.

Bottom line: an evaluation should result in architectural “Risks Themes”. See SEI’s web-site for details.

Error Handling on your Web Presence is Important

InoxMovies.com

showed me the following error message

Server Error in '/' Application.

---

Server was unable to process request. --> Object reference not set to an instance of an object.

Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.
Exception Details: System.Web.Services.Protocols.SoapException: Server was unable to process request. --> Object reference not set to an instance of an object.
Source Error:

An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

Stack Trace:

[SoapException: Server was unable to process request. --> Object reference not set to an instance of an object.]
   System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall) +431766
   System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters) +204
   WebReference.SeatBook.ShowSeats(Int64 TheatreId, Int64 BookingId, String ShowClass, Int64 NoOfTickets, String PartnerId, String PartnerPwd) +195
   seatlayout.Seat_Layout() +743
   seatlayout.Page_Load(Object sender, EventArgs e) +3161
   System.Web.Util.CalliHelper.EventArgFunctionCaller(IntPtr fp, Object o, Object t, EventArgs e) +14
   System.Web.Util.CalliEventHandlerDelegateProxy.Callback(Object sender, EventArgs e) +35
   System.Web.UI.Control.OnLoad(EventArgs e) +99
   System.Web.UI.Control.LoadRecursive() +50
   System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint) +627

---

Version Information: Microsoft .NET Framework Version:2.0.50727.3603; ASP.NET Version:2.0.50727.3082

This is an example of what not handling Exceptions does to the user experience.

GoF: Polymorphism, Encapsulation, Inheritance and Delegation

Polymorphism is when your client has a reference to an interface, and it’s concreate class can be one of many implementations. A different different behavior or value in a subclass can be utilized without a switch or an if. Parent class class defaults can be inherited and overridden where necessary. A method can be declared in a parent class, but each subclass can have a specialized implementation/logic of that method e.g. calculateArea();

Encapsulation is a core principal, it refers to the bundling of data with the methods that operate on that data. Basically, logic and data go together. If you have a class, with properties and logic together – it is encapsulated. Helps separation of concerns and reduces surface areas – also supports immutability – since only the object can control the data.

 
Inheritance is the ability of objects in an Object-Oriented language to inherit properties and methods of other objects e.g. in Java, use extends or implements keywords.

Delegation is when at runtime you can invoke a different object to complete a task dynamically. A useful OO pattern that has seen several implementations in Java EE.

The ability to frequently modify or add functionality, or quickly fix defects (Extensibility & Maintainability) comes from early design decisions.

All in all – these are core design principles – any object oriented analysis and design must respect, consider and apply these principles.

Gang of Four Patterns for Java EE developers : Cheat Sheet

Here is the list of Gang of Four patterns related with an actual implementation in Java EE. Read on – it will make sense (hopefully).

Strategy: EJB interface.

Defines a family of algorithms, encapsulates each one and makes them interchangeable. Strategy lets the algorithm vary independently from clients who use it.

Decorator: Dependency Injection.

Attach additional responsibilities to an object dynamically. Provide a flexible alternative to sub-classing for extending functionality.

Factory: EJBs .

Define an interface for creating an object, but let the subclasses decide which class to instantiate.

Chain: Filters.

Decoupled requester and handler. Chain the handlers, one of them must handle it.

Singleton: JNDI

Ensure a class only has one instance, and provide a global point of access

Flyweight: JDBC Connection Pooling.

JDN

Adapter : Use the same interface, but adapt to other classes.

Façade: Single point of entry for a sub-system.

Template: Defer implementation to subclass.

Builder: For complex varying structures.

Iterator: Access items in any collection implementation.

i18n APIs

If you’re designing an application that may be distributed to other nations, what you want to avoid is hardcoding English user text.

The following interfaces and objects are foundational to enable internationalization (i18n).

java.text package

Locale: Where is this running?

Resource Bundle: Alien language resource (LOL)

InputStreamReader OutputStreamWriter: UTF-8 and UTF-16

Internationalization is essential for a global impact

Abstraction, abstraction and more abstraction. Decouple everything with a minimal surface area allows for a low friction system. Internationalizing any application is probably a great test of software flexibility.

In order to prepare an application, several changes need to be considered:

1. Screen Text

2. Dates, Calendars

3. Numbers, Formats, Currency

4. Icons, Images

5. Text File formats (e.g. UTF-8, UTF-16).

 

It is possible that your program writes to ASCII, however that’s not going to work for the Japan market, you need to be able to write in UTF-16.

Distributed Garbage Collection and Stub Downloads–and other dirty solution architecture alternatives

Technology choices can make the difference between meeting the customers’ immediate needs and failing to complete a project on time. No can do if you’re using IIOP. If you’re still stuck in CORBA or IIOP, and trying to get remote objects talking to one another – don’t expect RMI-IIOP to help do what pure RMI does – DGC. Stub downloads and DGC are never going to be supported across technologies – it’s not possible to standardize it.

Think about refactoring to expose encapsulated business services instead. Use HTTP – it is connection based and stateless. Alternatively think about using messaging architectures, if you are at the systems programming level – IP Multicasting can be used of TCP that can serve as an unreliable messaging infrastructure – but it can also have layers of high speed health checks and retry mechanisms built. Virtual channels like queues (p2p) and topics with durability attributes can be used as well.

If a non-EJB Java application requires integration with your CORBA system, Java IDL is officially recommended – the communication protocol then is native IIOP. CORBA clients needs to talk to Java, Java IDL on the client end don’t make sense. If you want to integrate with the mainframe, and all you need is some fancy GUI, but the mainframe source code is unavailable – guess what? Screen scrapers via terminal emulator inputs may be recommended. Depends. If the goal is to meet the customer’s need quickly – don’t forget to do a trade off analysis and make target state recommendations. An architects job is to accelerate business not make perfect solutions at all costs. Judging trade offs is where we make money for the clients. Know when where and how to make short cuts if needed. Use a reverse proxy to target different servers for servicing different types of requests. Have failure management systems up to the wazoo. Avoid EJBs if you have no need for transactions and business logic in the solution. KISS.

If you must use CORBA and RMI-IIOP (for EJB type communications), and Session Beans provide good memory management like Pooling and Passivation (SLSB & SFSB). If you must integrate with existing native C++ code/business logic, it is advisable to wrap that with JNI calls, and remote it via RMI. Don’t over use web-services if you don’t need a business service. SOA isn’t API over the web.

All in all, Java IDL is business as usual for CORBA programming. Use RMI-IIOP is for Java programming over IIOP, it can interoperate with CORBA objects but those interfaces must be available as Java RMI. If you must use pure IIOP – then you have existing CORBA objects in play that can’t have Java interfaces – so you must use Java IDL. CORBA provides lots and lots of nice services; Naming Services, Security, Transaction Service, Event and Concurrency Control.

Regardless of how you meet your customers’ expectations – plan to leave them with an awesome build/deploy strategy & matching execution.

Creating Objects Design Situations

 

Understanding how to create an object goes beyond the new() syntax, a good designer will think about the current requirement and future requirements to ensure decoupling layers, build in flexibility and maintainability. For example,

So you have an object that needs to create another class, however

…it cannot anticipate the class of objects it must create

…it wants only its subclass to specify the object it wants to create

…it wants to localize knowledge of which helper subclass is the delegate

How would you design for these quality attributes?

How about the following:

A client class needs a complex object, however it also

… wants to vary the product’s internal representation

…isolate code for construction and representation

…gives you greater control over the construction process

How would you design for these quality attributes?

 

What if you wanted to:

… isolate the concrete class from the client that needs it, and

… allow for exchanging classes of products easily

…enforce a common consistent product interface across families of products

What’s going to be the pattern of choice, designer?

If you answered Factory, Builder and Abstract Factory – then that’s pretty darn good – you remember your GOFs, which are like the ABCs for software architects (or should be).

InoxMovies.com - an example of what NOT to do

One message for "InoxMovies.com" : Establish an Exception Handling Architecture

 

Server Error in '/' Application.

---

Server was unable to process request. --> Object reference not set to an instance of an object.

Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: System.Web.Services.Protocols.SoapException: Server was unable to process request. --> Object reference not set to an instance of an object.

Source Error:

An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

Stack Trace:

[SoapException: Server was unable to process request. --> Object reference not set to an instance of an object.] System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall) +431766 System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters) +204 WebReference.SeatBook.ShowSeats(Int64 TheatreId, Int64 BookingId, String ShowClass, Int64 NoOfTickets, String PartnerId, String PartnerPwd) +195 seatlayout.Seat_Layout() +743 seatlayout.Page_Load(Object sender, EventArgs e) +3161 System.Web.Util.CalliHelper.EventArgFunctionCaller(IntPtr fp, Object o, Object t, EventArgs e) +14 System.Web.Util.CalliEventHandlerDelegateProxy.Callback(Object sender, EventArgs e) +35 System.Web.UI.Control.OnLoad(EventArgs e) +99 System.Web.UI.Control.LoadRecursive() +50 System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint) +627

 

---

Version Information: Microsoft .NET Framework Version:2.0.50727.3603; ASP.NET Version:2.0.50727.3082

 

A Combination Algorithm

The problem: Write an algorithm that can provide combinations of a given word. The combinations need not contain a new word with the same letters.

Input: ABCDE

OUTPUT: ABCDE, ABCD, BCDE, ABC, BCD, CDE, AB, BC, CD, DE etc.

There are several algorithms out there that describe how to create effective combinations, SEPA does permutations, bubble sort and nested loops etc.

After spending some time looking for what’s been done - the one I liked the most was as follows: [0,0,0], [0,0,1], [0,1,1] [1,1,1]: null, A, AB ABC etc.

Incrementing decimals, start with zero, get a binary representation and map it to the array positions. This will give the combinations in constant time. A very efficient algorithm.

   /**
    * Take a word and return a collection of combinations
    * @param sortedWord
    * @return
    */
   public Collection<String> generateCombinations(String sortedWord)
   {
       Collection<String> c=new HashSet<String>();
       char[] broken=sortedWord.toCharArray();
       int combinationLength=new Double(Math.pow(2L, (new Long(sortedWord.length())).longValue())).intValue();
    //  System.out.println("Combination len="+combinationLength);
       for(int loop=combinationLength-1;loop>0;loop--)
       {
       String binary=fillWithZeros(Long.toBinaryString(loop),sortedWord.length());
       char[] bins=binary.toCharArray();
       StringBuffer wb=new StringBuffer();
       for(int a=0;a<bins.length;a++)
       {
           Integer binValue=new Integer(""+bins[a]);
           if(binValue.intValue()==1)
           {
            wb.append(broken[a]);  
           }
       }
       c.add(wb.toString());
       }

 

While there is a nested loop, the loops can be replaced with other techniques.

This is a very high performance combination creation technique. Comments/Improvements are welcome.

Are DSLs simply XML Hell?

DSL : what is it ? You have used a Domain Specific Language. Trust me. Demystify DSL: it simply a narrowed and specific semantic problem that solves a narrow set of problems.

Model-View-Controller (MVC) is a common pattern for Web development, Apache Struts has come to the rescue in the past. Each Struts application uses a configuration file (XML). The language (dialect) of the XML specifies exactly how the MVC pattern would be implemented for the specific implementation this is DSL.

Object Relational mapping was a common problem made worse by general purpose languages and APIs(e.g. Java and JDBC), along came the a natural ORM (e.g. Hibernate) with specific configuration files that mapped POJOs to Tables. The configuration file (XML) supported a dialect (ORM DSL), of course it was not called DSL back then they were simply configuration files (aka XML Hell).

DSLs don’t necessarily mean XML. For example, running rules in Java was ‘simplified’ by a Rules Engine implementation e.g. Jess. This used a DSL - Jess 7 has its own declarative XML rule language called "JessML" (a DSL).

What is the advice for people who are trying to learn DSLs and master them ? Don’t. Try not to master DSLs instead focus on the domain of the problem, understand the software architecture and how it fits, understand what the pattern of problems are, figure out how best to apply design patterns that solve them. Understand the pain of the domain (e.g. web-site design, object-relational mapping framework, rules etc), understand the inefficiencies, then focus on an over all design within the domain that solves most of the problems. Finally, look at the DSL as a tool to solve the problems in a specific efficient way. Then you will see there is no XML but simply a graceful solution.