Git Product home page Git Product logo

bricks's Introduction

Bricks

Build Status Codecov Status Codacy Status DepShield Status License

Bricks is a framework that allows you to create automated documentation about an application and its components. The framework is easy to integrate and offers maximum flexibility to document any type of application.

Tools like Structurizr, CodeScene or Arc42 are very powerful, but cost money and / or require a lot of training. That's why we wanted to create an easy to use alternative that is flexible and easy to customize and expand.

Our primary goals are:

  • Build documentation based on conventions and largely generated information.
  • Storage of the generated documentation together with the component itself.
  • An easy to extend framework to document different types of applications (monolithic, microservice based).
  • Offer visualization of the collected information in the form of a dashboard and documents that can be reused offline.

Modules

The project consists of the following modules:

  • bricks-model contains the base model. It provides the abstract description of an application and its components. The definition of the model follows a concrete idea of ​​what information is needed to describe an application and its components. Nevertheless, it tries to be as flexible and expandable as possible.
  • bricks-converter contains code to convert the model from/to a raw format (like json, yaml, binary or proprietary).
  • bricks-discover contains all the necessary parts to discover parts of a component based on source code, build and meta information.
  • bricks-maven-plugin includes a Maven plugin that allows for the repetitive creation of documentation during the components build process.
  • bricks-assemble contains all the necessary parts to collect the generated documentation from different 'places' and make it available as a data model.
  • bricks-analyze contains code to analyze the model and to calculate or aggregate certain aspects.
  • bricks-visualize contains visualization code for the model. This includes the output of the documentation as svg, ppt, pdf and other formats.
  • bricks-dashboard contains a Spring Boot application that processes and displays the generated components of an application and its components.
  • bricks-example contains examples that make certain use cases clearer.

License

This code is open source software licensed under the Apache 2.0 License.

bricks's People

Contributors

ingogriebsch avatar uweschaefer avatar

Watchers

 avatar  avatar

bricks's Issues

Explicitly configure standard maven plugins

From @britter

Furthermore I recommend to explicitly configure standard plugins like maven-compiler-plugin and maven-surefire-plugin because otherwise you will get pretty out dated default versions from the default-bindings.xml

Introduce visualizer to visualize a component communication

  • Implementation should create svg.
  • Svg shows the selected component in the center.
  • All in some way 'connected' components are shown in a circle around the selected component.
  • A directed and colored arrow is shown for each direct communication.
  • A directed and colored arrow is shown for each indirect communication.
  • The different communication layers can be hidden through the layer mechanism of the svg.
  • Each component is shown as a hexagon with it's name in the center.
  • The boarder color of each component matches it's corresponding layer color.

Remove boilerplate code from model

As the Model should be concise and very easy to read, things like putting private in front of every field can be considered visual noise.

i'd leave it to lombok. (i'll attach a PR)

feel free to drop it, if this is considered too lomboky for you :D

Introduce module 'visualize' to allow the implementation of specific visualizer's

First idea for a 'Visualizer' interface:

public interface Visualizer<I, O> {
    void visualize(I input, O output) throws Exception;
}

First idea for an 'ApplicationVisualizer interface:

public interface ApplicationVisualizer<T> extends Visualizer<Application, O> {
}

First idea for an 'ComponentVisualizer interface:

public interface ComponentVisualizer<T> extends Visualizer<Component, O> {
}

Error on initial import in eclipse

If the project is not yet installed, eclipse reports an error:

Failed to execute goal on project �[36mbricks-maven-plugin�[m: �[1;31mCould not resolve dependencies for project com.github.ingogriebsch.bricks:bricks-maven-plugin:maven-plugin:1.0.0-SNAPSHOT: Could not find artifact com.github.ingogriebsch.bricks:bricks-model:jar:1.0.0-SNAPSHOT�[m (org.apache.maven.plugins:maven-plugin-plugin:3.6.0:descriptor:mojo-descriptor:process-classes)

org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal on project �[36mbricks-maven-plugin�[m: �[1;31mCould not resolve dependencies for project com.github.ingogriebsch.bricks:bricks-maven-plugin:maven-plugin:1.0.0-SNAPSHOT: Could not find artifact com.github.ingogriebsch.bricks:bricks-model:jar:1.0.0-SNAPSHOT�[m
	at org.apache.maven.lifecycle.internal.LifecycleDependencyResolver.getDependencies(LifecycleDependencyResolver.java:269)

...
	pom.xml	/bricks-maven-plugin	line 122	Maven Build Problem

Questionable if this is worth fixing, but the solution obviously is to mvn install. Just wanted to mention it here for future reference.

Implement yaml based ComponentIdCollector to avoid hard coded configuration of ids

  • Collector should extract ids from yaml file.
  • Should be possible to configure a 'base path' as root of entries inside yaml.
  • Should be possible to configure a placeholder as part of the 'base path' to allow to map the application id given while exeucting the collector.
  • Should be possible to configure the key which value contains the application id.

Introduce view model to not use data model directly

  • Introduce different view models for application (overview, etc)
  • Introduce different view models for componet (overview, etc)
  • Clarify if view model should always map view or if different abstract view models are sufficient

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.