Bauklotz

A Python-based tool for software architecture analysis and visualization.

Overview

Bauklotz is a framework for building and executing analysis pipelines that process software project structures. It is designed to help software architects analyze codebases through configurable filters and generate various reports and visualizations.

Features

• Pipeline-based architecture analysis
• Configurable filters for analyzing Python projects
• Multiple report formats (CSV, YAML, UML diagrams, C4 diagrams, Treemaps)
• Graph-based visualization of class hierarchies and dependency networks
• C4 model extraction from docstring annotations
• Extensible filter and report system
• Plugin system for custom filters and reports
• Fact contract validation: static pre-run check that every filter's required facts are provided by upstream filters

Installation

pip install bauklotz

Usage

1. Create a configuration file describing your analysis pipeline:

channel input

filter builtin.python.project:PythonProjectFilter project
filter builtin.python.structure:PythonClassHierarchyFilter hierarchy
    internal_modules: "your_module"

# External filter example
filter external.metrics:ComplexityFilter complexity
    threshold: 10

report builtin.writer.uml:ClassDiagramWriter classdiagram
   path: "output/classdiagram.uml"

input -> project -> hierarchy -> complexity -> classdiagram

2. Run the analysis:

bauklotz config.bauklotz <project_dir> input --extension external

Configuration

The pipeline is configured using a simple DSL that defines:

• Input channels
• Filters for processing (both built-in and external)
• Reports for output generation
• Connections between components

Syntax Notes

A few DSL conventions that aren't obvious from the example above:

• Argument names always end with a colon, e.g. threshold: (the colon is stripped from the parsed name).
• A value prefixed with @ is treated as a file path, e.g. path: @output/summary.csv; relative paths are resolved relative to the config file's directory.
• Numeric argument values (e.g. threshold: 10) are always parsed as floating point numbers internally.
• # starts a comment that runs to the end of the line; a # inside a "quoted string" is treated as a literal character, not a comment.

Plugin System

Bauklotz supports external filters and reports through its plugin system. Custom filters can be added by:

1. Creating a Python module with filter implementations
2. Registering the module with Bauklotz
3. Referencing the custom filters in your configuration using external.module:FilterName syntax

Core Components

• Pipe: Base interface for pipeline construction and execution
• Filter: Processes items in the pipeline
• Report: Generates output in various formats

Output Formats

• CSV reports
• YAML summaries
• UML class diagrams
• Graph formats (GML)
• C4 architecture diagrams (PlantUML)
• Interactive Treemaps (HTML)

Documentation

For detailed documentation, please visit the project repository.

License

BSD3