How it all fits together

Structure101 empowers you to improve your architecture while integrating seamlessly with your existing workflow, regardless of what tools you use for development, build and testing.

With specific integrations for ...

Structure101 ADE & IDE plugin

Using the Structure101 Architecture Development Environment (ADE)1, architects manipulate the model (the Levelized Structure Map), to determine what concrete actions should be taken to better organize the code. Structure101 models are derived directly from the code 2.

The architects' work is captured in the form of Architecture Diagrams (rules)3a and Action Lists3b (recommended changes).

Developers who use Eclipse, Visual Studio or IntelliJ receive the architecture diagrams and action lists right inside their IDE4. Architecture diagrams guide conformance, while violations are highlighted on the diagrams, and raise edit-time warnings. A mouse click takes the developer direct to the source of a violation.

In the case of an existing codebase, the plugin can be configured to highlight only new violations so that developers are not overwhelmed by warnings, yet can ensure that the architecture never deteriorates further.

Actions designed by the architect to improve the overall organization of the codebase, are presented and can be implemented en masse, or over time, and at a pace that suits the team's release schedule.

Structure101 Build & Continuous Integration

Structure101 Build5 comprises a simple but powerful set of command line utilities, that integrates easily with almost any continuous integration environment, including off-the-shelf integration with Hudson/Jenkins, Maven and Sonar.

No matter how bad (or good) things are with your codebase, make sure it doesn't degrade over time.

Better still actively use the KALOI principle to gradually improve your codebase as you move from one iteration to the next.

Automatically create customizable, detailed or summary reports

with data on the size, composition, structure, complexity and architectural integrity of each build.

Structure101 Repository

The Structure101 Repository is a light-weight, low maintenance, file-based XML data-store repository. It can be accessed locally, or remotely (once the Structure101 Web Application has been installed). It stores the target architecture, action-lists and all architecture related data for each published snapshot of your build.

Structure101 Webapp

The Structure101 Web Application6 web-enables a Structure101 repository, providing high-level trending and cross-project reports on the status and integrity of your software architecture.

Information available includes:

Architecture diagrams

Dependency matrices

New dependencies and violations

Size and over-complexity stats

Summary reports

Information available only through the web
application:

Cross-project size, complexity and violation charts

Size, complexity and violation trends

Dependencies and violations that have been removed

As well as making the information available in a web browser, the web
application supports RSS feeds that notify of changes in your software architecture.

Tools

Structure101 puts a whole array of tools at your disposal as you work towards improving the modularity of your codebase.

Reorganizing

Discover & define an acyclic architecture

With Structure101 you can reorganize an existing, monolithic, unstructured code-base into one with the essential properties of modularity.

Back in the 90's John Lakos wrote one of the defining software engineering texts, Large-scale C++ Software Design, which introduced the concept and importance of levelization in software development.

With a rich set of viewing and filtering options, tune the LSM for the specific task at hand. Then manipulate the model using drag 'n' drop, optimizing the organization of your code into acyclic, "mind-sized chunks" throughout.

Visualization

Understand

In order to discover your architecture you need to first understand it.

Communication

All on the same page

Architecture is communicated to the development team through the IDE, showing errors or warnings on violations.

Ongoing trends and cross project monitoring are available to the whole team via the Structure101 Web Application and Sonar plugin.

Build

Don't do it!

With support for Ant, Hudson, Jenkins, Maven, MS Build etc Structure101 integrates into your build to ensure the team stick to the defined architecture.

Scalability

Works for the largest codebases

We know, scalability is not a "tool", but it is worth mentioning. Organizing an entire codebase requires tools that are performant even when working with the very largest codebases. We’ve run Structure101 against 16,000,000 lines of code, our customers use it on more.

Organize your codebase

Almost all codebases carry too much complexity. Code is complex but it should never be excessively so.

At the heart of Structure101 is the "model" of your code, presented as a Levelized Structure Map (or 'LSM').

The LSM is tuned specifically for removing excessive complexity and organizing a codebase so developers know how best to add, change and test code.

Using the LSM to browse a well-organized codebase vs. one with little (or poor) organization is guaranteed to convince the sceptics of the value of organization.

"Mind-sized chunks" with low and controlled coupling at every level of the codebase (packages, namespaces, classes, etc.) is the ideal - the LSM is your gateway.

Working within the LSM you manipulate the model, driving the over-complexity chart toward the origin - no tangles, no fat.

This can take time, from a matter of hours to days, depending on size and complexity. The Icefaces example below, a small codebase, took several hours.

Note, there is no risk. You are working with a model of the code.

Once optimized you have the option to a) push the ensuing "action list" out to the developers for implementation, and/or b) create architecture diagram(s) that define your architecture and drive the development team.

In the latter case, you are ensuring your architecture never deteriorates again, while taking the less invasive, phased approach to implementing changes.

Tagging and filtering

Often there will be visible items not relevant to the task, making it difficult to find a solution. Structure101 provides the ability to tag () and filter items, in () and out, () so you can focus exclusively on the task at hand.

Context menu

In addition to the toolbar of viewing options, right-click for context menu for a selection of commands to help you organize your codebase.

Auto-levelize

Our favorite Structure101 feature, auto-levelize (), first removes all hierarchy, "flattening" selected items to their leaf items. It then analyzes the result before recreating the hierarchy based on the natural occurring dependencies between the flattened items.

Review and rename

Auto-levelization results in automatically named containers, where the name indicates number of children and size. Review the results and assign appropriate names. Working from the bottom up, suitable identifiers emerge with surprising ease.

Publish

Finally, either a) publish () the action list for implementation, and/or b) derive an architecture diagram () for guiding the development team towards your target architecture.

Related Materials

Visualize & understand

The first step to controlling something is to understand it. Structure101 creates a model of your code in seconds, and then lets you browse and analyze its structure in different ways: using levelized structure maps, dependency structure matrices, directed graphs etc.

See the dependencies within your code-base at any level, across levels and using different hierarchies: method-to-method, function-to-type, class-to-class, namespace-to-class, directory-to-directory, jar-to-method, etc.

1

2

3

4

5

6

7

8

Levelized structure map ('LSM')

The LSM shows dependencies across layers. A wide range of intelligent grouping options and filters remove the clutter and let you focus purely on the problem to hand.

Dependency structure matrix ('DSM')

The DSM, although less intuitive, scales well for larger graphs.

Top level dependency graph

Visualize and understand the dependencies at the highest levels of your codebase. In this case, graphing the dependencies between Maven POMs.

Measure, compare & trend

Structure101 provides a simple but powerful measurement framework ('XS') focused purely on codebase structure. It lets you define complexity limits at any level of decomposition (design, package, class and method).

XS considers just two structural measures - "Fat" (too much in the one container - class, package, jar etc) and "Tangle" (cyclic dependencies).

An XS value of zero is good - it means that the code is not excessively complex and has not exceeded user defined limits.

In the event of exceeding thresholds, Structure101 will take you directly to specific violations, as well as giving you an overview of how violations are distributed across your code-base.

XS can be trended over time to ensure you are driving your codebase toward zero excessive (or unnecessary) complexity.

1

2

3

4

5

Drilldown

Structure101 relates the amount of XS (red) to the amount of code in an item so that you can compare the size and complexity of the different areas of your code-base. While you can drilldown into the area of greatest interest.

Offenders

A list of items that violate user defined thresholds helps you prioritize problems and tackle them according to the impact they are having on productivity.

Filter results

A pie chart shows you the relative contribution of problems to the overall XS value. Selecting a slice of the pie filters the list to show just items with the selected problem.

Summary reports

Sometimes you will just want a quick overview of the current state - especially if you're just starting to look at your structure.

Project & cross-project reports and trends

The Structure101 web application provides much more detailed reports, including trending structural data over time and cross project comparisons.

Dependency management & impact analysis

For any dependency, at any level of composition, discover the dependency's source with the click of the mouse.

Even where the code-base has become overly complex and unstructured, Structure101 gives you ways to cut through the raw structural data and make sense of it all.

1

2

3

4

5

6

7

8

9

Impact analysis

Using tagging and filtering it is easy to carry out comprehensive impact analysis when code needs changing. In this instance, you only see code that is in the dependency closure of getDownstreamProjects. There are methods and fields inside classes that are not shown as they are not used by getDownstreamProjects.

Auto-partitioning

The Auto-partition button partitions a large graph into its natural clusters, making it easier to understand and analyze complexity.

Slices

Dependencies cause other dependencies at different levels so Structure101 gives you access to different slices. In this case, the "leaf package" level is selected and we see that there is one disruptive tangle consisting of 20 nodes spread across 11 parent packages.

Dependency breakout - hierarchy

The hierarchy of items that cause the dependency.

Dependency breakout - classes

All the classes that cause the dependency.

Dependency breakout - references

The list of references that cause the dependency.

Notables

Dropdown lists of notables let you zero in on problem areas and areas of interest.

Notables...

are context-sensitive giving you the information you need where you need it.

Start with an empty diagram

Creating the simplest of diagrams defines an architecture. Dependencies in architecture diagrams are implicit, cells should only be used by cells in higher layers. "MyApp" can use "Data" and "Util", no other dependencies are allowed.Note: in this case cells are greyed out as there is no code associated with the cells.

Or create direct from code

Again, no visible dependencies, in other words "no violations to the defined architecture". Note: cells are not greyed out, there is code associated with each cell.

Or create from the model

Using the rich modelling capabilities of our LSM, manipulate the model of your code until it accurately reflects your desired architecture. Two more clicks (create & publish) and that model has the whole team understanding and working towards the same architecture.

Violations

Up arrows indicate cyclic dependencies, violations to the defined architecture. "mulitpart" is illegally using "context" and "filter".

Prevent specific dependencies

Often there is a need to restrict access to certain code elements, not just simply banning cyclic dependencies, "A" should never use "B". Right click for the context menu to create an override top to bottom, in this case preventing "web" using "validation", a valid dependency under default rules.

Ignore cyclic dependencies

At times there is a need to simply ignore a cyclic dependency, maybe there's just too many. Again right click for the context menu to create an override bottom to top, in this case permitting "validation" to use "web", an illegal dependency under default rules.

Modules need privacy too

Many languages support the concept of classes with private members and data. Structure101 extends the concept of privacy. In this case, 2 sub-packages of the "jmx" package are marked as private. As the "support" sub-package is accessed externally, there is a violation. Enforce your APIs.

Related Materials

Organize your codebase

Almost all codebases carry too much complexity. Code is complex but it should never be excessively so.

At the heart of Structure101 is the "model" of your code, presented as a Levelized Structure Map (or 'LSM').

The LSM is tuned specifically for removing excessive complexity and organizing a codebase so developers know how best to add, change and test code.

Using the LSM to browse a well-organized codebase vs. one with little (or poor) organization is guaranteed to convince the sceptics of the value of organization.

"Mind-sized chunks" with low and controlled coupling at every level of the codebase (packages, namespaces, classes, etc.) is the ideal - the LSM is your gateway.

Working within the LSM you manipulate the model, driving the over-complexity chart toward the origin - no tangles, no fat.

This can take time, from a matter of hours to days, depending on size and complexity. The Icefaces example below, a small codebase, took several hours.

Note, there is no risk. You are working with a model of the code.

Once optimized you have the option to a) push the ensuing "action list" out to the developers for implementation, and/or b) create architecture diagram(s) that define your architecture and drive the development team.

In the latter case, you are ensuring your architecture never deteriorates again, while taking the less invasive, phased approach to implementing changes.

Tagging and filtering

Often there will be visible items not relevant to the task, making it difficult to find a solution. Structure101 provides the ability to tag () and filter items, in () and out, () so you can focus exclusively on the task at hand.

Context menu

In addition to the toolbar of viewing options, right-click for context menu for a selection of commands to help you organize your codebase.

Auto-levelize

Our favorite Structure101 feature, auto-levelize (), first removes all hierarchy, "flattening" selected items to their leaf items. It then analyzes the result before recreating the hierarchy based on the natural occurring dependencies between the flattened items.

Review and rename

Auto-levelization results in automatically named containers, where the name indicates number of children and size. Review the results and assign appropriate names. Working from the bottom up, suitable identifiers emerge with surprising ease.

Publish

Finally, either a) publish () the action list for implementation, and/or b) derive an architecture diagram () for guiding the development team towards your target architecture.

Related Materials

Visualize & understand

The first step to controlling something is to understand it. Structure101 creates a model of your code in seconds, and then lets you browse and analyze its structure in different ways: using levelized structure maps, dependency structure matrices, directed graphs etc.

See the dependencies within your code-base at any level, across levels and using different hierarchies: method-to-method, function-to-type, class-to-class, namespace-to-class, directory-to-directory, jar-to-method, etc.

1

2

3

4

5

6

7

8

Levelized structure map ('LSM')

The LSM shows dependencies across layers. A wide range of intelligent grouping options and filters remove the clutter and let you focus purely on the problem to hand.

Dependency structure matrix ('DSM')

The DSM, although less intuitive, scales well for larger graphs.

Top level dependency graph

Visualize and understand the dependencies at the highest levels of your codebase. In this case, graphing the dependencies between Maven POMs.

Measure, compare & trend

Structure101 provides a simple but powerful measurement framework ('XS') focused purely on codebase structure. It lets you define complexity limits at any level of decomposition (design, package, class and method).

XS considers just two structural measures - "Fat" (too much in the one container - class, package, jar etc) and "Tangle" (cyclic dependencies).

An XS value of zero is good - it means that the code is not excessively complex and has not exceeded user defined limits.

In the event of exceeding thresholds, Structure101 will take you directly to specific violations, as well as giving you an overview of how violations are distributed across your code-base.

XS can be trended over time to ensure you are driving your codebase toward zero excessive (or unnecessary) complexity.

1

2

3

4

5

Drilldown

Structure101 relates the amount of XS (red) to the amount of code in an item so that you can compare the size and complexity of the different areas of your code-base. While you can drilldown into the area of greatest interest.

Offenders

A list of items that violate user defined thresholds helps you prioritize problems and tackle them according to the impact they are having on productivity.

Filter results

A pie chart shows you the relative contribution of problems to the overall XS value. Selecting a slice of the pie filters the list to show just items with the selected problem.

Summary reports

Sometimes you will just want a quick overview of the current state - especially if you're just starting to look at your structure.

Project & cross-project reports and trends

The Structure101 web application provides much more detailed reports, including trending structural data over time and cross project comparisons.

Dependency management & impact analysis

For any dependency, at any level of composition, discover the dependency's source with the click of the mouse.

Even where the code-base has become overly complex and unstructured, Structure101 gives you ways to cut through the raw structural data and make sense of it all.

1

2

3

4

5

6

7

8

9

Impact analysis

Using tagging and filtering it is easy to carry out comprehensive impact analysis when code needs changing. In this instance, you only see code that is in the dependency closure of getDownstreamProjects. There are methods and fields inside classes that are not shown as they are not used by getDownstreamProjects.

Auto-partitioning

The Auto-partition button partitions a large graph into its natural clusters, making it easier to understand and analyze complexity.

Slices

Dependencies cause other dependencies at different levels so Structure101 gives you access to different slices. In this case, the "leaf package" level is selected and we see that there is one disruptive tangle consisting of 20 nodes spread across 11 parent packages.

Dependency breakout - hierarchy

The hierarchy of items that cause the dependency.

Dependency breakout - classes

All the classes that cause the dependency.

Dependency breakout - references

The list of references that cause the dependency.

Notables

Dropdown lists of notables let you zero in on problem areas and areas of interest.

Notables...

are context-sensitive giving you the information you need where you need it.

Start with an empty diagram

Creating the simplest of diagrams defines an architecture. Dependencies in architecture diagrams are implicit, cells should only be used by cells in higher layers. "MyApp" can use "Data" and "Util", no other dependencies are allowed.Note: in this case cells are greyed out as there is no code associated with the cells.

Or create direct from code

Again, no visible dependencies, in other words "no violations to the defined architecture". Note: cells are not greyed out, there is code associated with each cell.

Or create from the model

Using the rich modelling capabilities of our LSM, manipulate the model of your code until it accurately reflects your desired architecture. Two more clicks (create & publish) and that model has the whole team understanding and working towards the same architecture.

Violations

Up arrows indicate cyclic dependencies, violations to the defined architecture. "mulitpart" is illegally using "context" and "filter".

Prevent specific dependencies

Often there is a need to restrict access to certain code elements, not just simply banning cyclic dependencies, "A" should never use "B". Right click for the context menu to create an override top to bottom, in this case preventing "web" using "validation", a valid dependency under default rules.

Ignore cyclic dependencies

At times there is a need to simply ignore a cyclic dependency, maybe there's just too many. Again right click for the context menu to create an override bottom to top, in this case permitting "validation" to use "web", an illegal dependency under default rules.

Modules need privacy too

Many languages support the concept of classes with private members and data. Structure101 extends the concept of privacy. In this case, 2 sub-packages of the "jmx" package are marked as private. As the "support" sub-package is accessed externally, there is a violation. Enforce your APIs.