Skip to content
Tool to visualize and maintain the composition of java code.
Java JavaScript HTML Shell CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Socomo - care about the composition of your java code

Maven Central GitHub Release License Issues

Socomo is a simple tool to visualize the composition of your source code and track changes to the composition as you progress with the development of your java project. You can use this tool to:

  • Explain internal design of your modules by showing the diagram of component dependencies.
  • Assure that architecture of your project is not being broken by seeing what new dependencies are added.
  • Brag on your blog or twitter how great the structure of your code is, proving it with the diagrams.

See Socomo in action on the Guava project:

Composition of Guava viewed in Socomo

Quick Start

Try it now on your code! For a project build with maven do this:

mvn pl.gdela:socomo-maven:display

Alternatively, for a jar file, download the latest release and do this:

java -jar socomo-standalone.jar -d path/to/your.jar

Either of the above commands generates the socomo.html file and opens it in the browser. You'll be presented with an interactive visualization of the structure of the code.

To track changes to the composition commit the socomo.html file to your source code repository and add socomo maven plugin to your project. Whenever composition changes the plugin updates this human-readable file, so you'll have a history of changes in the most convenient place - in your source code repository.

How to Read Diagrams

The diagram shows composition of your code at some specific level, typically the topmost package of the project. Each subpackage at this level is a component represented as node in the diagram. Components are arranged on the diagram to form layers: a component uses other components that are below it, and is used by components that are above it.

Composition of sample e-commerce project

The actual dependencies analyzed from the bytecode are represented as edges. The wider the edge, the stronger is the dependency between components.

When you select a component, blue edges show outgoing dependencies pointing to components used by the selected one, and brown edges show incoming dependencies from the components that use the selected one. Red edges are dependencies that point upwards, against the layers, and thus are the cause of a cyclic dependency between two or more components.

Best Practices for Composition

Socomo is an opinionated tool that requires you to structure the code in the right way to be most useful:

  1. Make your topmost components speak about the business. They shouldn't tell which frameworks do you use. The technical details are more familiar to a developer and thus less important than the business domain.

  2. Keep your dependencies acyclic. If two components depend on each other, you cannot understand and work on them one at a time, they actually form one larger component.

  3. Let your components be balanced in size. Having one huge component amongst tens of smaller ones defies the whole purpose of dividing the code.

Those principles will help you avoid your project being a big ball of mud.

Socomo Maven Plugin

Add following snippet to the <build><plugins> section in your pom.xml file. For multi-module projects, you can add it just to the parent pom, so that it is inherited by all modules.


The level property is optional, if not given it will be guessed. The plugin should be bound to a phase that is executed after your code has been compiled, so by default it is bound to the package phase.

Socomo Standalone

Download the latest release and do this to get help how to use it:

java -jar socomo-standalone-*.jar --help


Raise an issue or enhancement request, or better yet a pull request. Contact me at or @WojciechGdela.

To develop Socomo you need Maven and Node/Npm installed on your machine. Then:

  1. Run mvn install to install a snapshot version of Socomo in your local maven repository.
  2. Use socomo maven plugin with the snapshot version or socomo standalone from socomo-core/target directory to produce a socomo.html file.
  3. Optionally you can use the or scripts that perform both of the above at once.
  4. Run npm --prefix socomo-view run serve to start serving *.js and *.css asset files.
  5. Open the generated socomo.html file in the browser. Assets can be developed in-place, the browser will automatically reload them.


Socomo is designed for simplicity and ease of use. If you would like to dig deeper into your code structure or enforce some rules about dependencies, consider alternatives listed below.

Stan4J - simplest one to use, allows you to dig deeper into your code structure and analyze dependencies in detail.

Structure101 - comprehensive toolset to explore structure of your code, analyze dependencies between code elements, define desired architecture of the code, integrate with build systems to detect violations and track structure changes.

Lattix - similar to the above, but focused on visualization using dependency structure matrix instead of graph diagrams.

Most of the above have plugins for SonarQube, a widely used "Continous Inspection" system. They can also be used from within IntelliJ/Eclipse, though having a standalone GUI for visualizing software structure feels more ergonomic.

Tools that used to be useful once, but now are outdated and no longer maintained: JDepend, Classycle, Macker, Architexa.

You can’t perform that action at this time.