DOCSEARCHbyAlgolia
Submit Docs

PyStructurizr

repository·master·Indexed 40 days ago

https://github.com/nielsvanspauwen/pystructurizr

A Python DSL for generating C4 architecture diagrams that implements the core concepts of the Structurizr DSL. It allows for modeling complex systems using Python logic, loops, and modules. The tool includes a CLI with commands to dump models to Structurizr DSL, run a live-preview development server via `dev`, and build SVGs for upload to Google Cloud Storage via `build`.

Tokens
2.2K
Snippets
13
Records
15
Agent score
98%

What's inside PyStructurizr

  1. Model complex systems using multiple modules

    master

    PyStructurizr allows you to model large systems by splitting definitions into separate Python modules. This is useful when different teams (e.g., Team A and Team B) own different parts of a system.

    Common patterns include:

    • Domain-specific files: Create files like users.py for people/actors, chatsystem.py for one software system, and analysissystem.py for another.
    • Shared definitions: Modules can share common definitions, such as Person objects or shared infrastructure containers.
    • Workspace aggregation: Use a central workspace.py file to import the different models and define top-level relationships between the separate software systems.
    • View definitions: Define specific view files (e.g., systemlandscapeview.py, containerview.py) to specify which parts of the aggregated model should be rendered as SVGs.

  4. Define C4 models and views with PyStructurizr

    master

    PyStructurizr uses a context manager pattern to define a Workspace, its Model, and subsequent Views. You can define elements like Person, SoftwareSystem, and Container, establish relationships using methods like .uses(), and create views by calling view methods on the workspace object.

    Key workflow:

    1. Use with Workspace() as workspace: to initialize the workspace.
    2. Use with workspace.Model(...) as model: to define architecture elements.
    3. Define relationships outside the model context if elements are captured in variables.
    4. Call view methods (e.g., workspace.ContainerView(...)) to create visualizations.
    from pystructurizr.dsl import Workspace

# Create the model(s)
with Workspace() as workspace:
    with workspace.Model(name="model") as model:
        user = model.Person("User")
        with model.SoftwareSystem("Software System") as software_system:
            webapp = software_system.Container("Web Application")
            db = software_system.Container("Database")

    # Define the relationships
    user.uses(webapp, "Uses")
    webapp.uses(db, "Reads from and writes to")

# Create a view onto the model
workspace.ContainerView(
    software_system, 
    "My Container View",
    "The container view of our simply software system.
)

  5. Build PyStructurizr from source

    master

    To build the PyStructurizr package from source, install the necessary dependencies from requirements.txt and then use setup.py to generate the source distribution and wheel files.

    $ pip install -r requirements.txt
$ python setup.py sdist bdist_wheel

  6. Build and upload views to Google Cloud Storage

    master

    To build the diagrams and upload the resulting SVGs to Google Cloud Storage (GCS), use the build command. You must provide the --view path, the --gcs-credentials file path, the target --bucket-name, and the destination --object-name.

    $ pystructurizr build --view examples.module_example.systemlandscapeview --gcs-credentials <...> --bucket-name <...> --object-name <...>

  8. Test PyStructurizr locally before deployment

    master

    To verify the package works correctly before uploading to PyPi, create a virtual environment, install the current directory, and run the pystructurizr dev command with a specific view from the examples.

    Note: The example view used below is examples.module_example.chatsystem_containerview.

    $ python -m venv myenv
$ source myenv/bin/activate
$ pip install .
$ pystructurizr dev --view examples.module_example.chatsystem_containerview
$ deactivate
$ rm -fr myenv

  9. Convert to SVG and upload to Google Cloud Storage

    master

    Generate SVG versions of your diagrams and upload them directly to a GCS bucket. This command uses kroki.io under the hood to generate the SVGs, meaning no local Structurizr DSL tools are required, but your diagram code will be sent to the online service.

    Flags:

    • --view <path_to_view_file>: The path to your Python view file.
    • --gcs-credentials <path_to_credentials_json_file>: Path to your Google Cloud credentials JSON.
    • --bucket-name <string>: The target GCS bucket name.
    • --object-name <string>: The name of the object to be created in the bucket.
    pystructurizr build --view <path_to_view_file> --gcs-credentials <path_to_credentials_json_file> --bucket-name <string> --object-name <string>

  12. PyStructurizr CLI Reference

    master

    The PyStructurizr CLI provides three main subcommands for managing Structurizr diagrams via Python code:

    CommandDescription
    dumpOutputs the generated diagram code or a JSON representation of the code and imported modules.
    devStarts a live-reloading development server to preview changes to your views in real-time.
    buildGenerates an SVG from a view and uploads it to Google Cloud Storage.