# Structurizr for the `buildzr`s 🧱⚒️
`buildzr` is a [Structurizr](https://structurizr.com/) authoring tool for Python programmers.
If you're not familiar with Structurizr, it is both an open standard (see [Structurizr JSON schema](https://github.com/structurizr/json)) and a [set of tools](https://docs.structurizr.com/usage) for building software architecture diagrams as code. Structurizr derive its architecture modeling paradigm based on the [C4 model](https://c4model.com/), the modeling language for visualizing software architecture.
`buildzr` offers flexible and fluent APIs to write software architecture models,
leveraging the standard Structurizr JSON schema for interoperability with
various rendering and authoring tools.
# Quick Start 🚀
## Installation
You can use `pip` to install the `buildzr` package:
```bash
pip install buildzr
```
## Creating a workspace
The module `buildzr.dsl` contains all the classes you need to create a workspace containing all the architecture models.
Below is an example, where we:
1. Create the models (`Person`, `SoftwareSystem`s, the `Container`s inside the `SoftwareSystem`, and the relationships between them)
2. Define multiple views using the models we've created before.
```python
import os
import json
from buildzr.encoders import JsonEncoder
from buildzr.dsl import (
Workspace,
SoftwareSystem,
Person,
Container,
SystemContextView,
ContainerView,
desc,
Group,
)
w = Workspace('w')\
.contains(
Group(
"My Company",
Person('Web Application User').labeled('u'),
SoftwareSystem('Corporate Web App').labeled('webapp')
.contains(
Container('database'),
Container('api'),
)\
.where(lambda s: [
s.api >> "Reads and writes data from/to" >> s.database,
])
),
Group(
"Microsoft",
SoftwareSystem('Microsoft 365').labeled('email_system'),
)
)\
.where(lambda w: [
w.person().u >> [
desc("Reads and writes email using") >> w.software_system().email_system,
desc("Create work order using") >> w.software_system().webapp,
],
w.software_system().webapp >> "sends notification using" >> w.software_system().email_system,
])\
.with_views(
SystemContextView(
lambda w: w.software_system().webapp,
key='web_app_system_context_00',
description="Web App System Context",
auto_layout='lr',
exclude_elements=[
lambda w, e: w.person().user == e,
]
),
ContainerView(
lambda w: w.software_system().webapp,
key='web_app_container_view_00',
auto_layout='lr',
description="Web App Container View",
)
)\
.get_workspace()
# Save workspace to a JSON file following the Structurizr JSON schema.
w.to_json('workspace.json')
```
Here's a short breakdown on what's happening:
- In `Workspace(...).contains(...)` method, we define the _static_ C4 models (i.e., `Person`, `SoftwareSystem`, and the `Container`s in the software system).
- In the `Workspace(...).contains(...).where(...)`, we define the relationships between the C4 models in the workspace. We access the models via the `w` parameter in the `lambda` function, and create the relationships using the `>>` operators.
- Once we have all the models and their relationships defined, we use (and re-use!) the static models to create multiple views to tell different stories and show various narrative to help document your software architecture.
- Finally, we write the workspace definitions into a JSON file, which can be consumed by rendering tools, or used for further processing.
The JSON output can be found [here](examples/system_context_and_container_view.json). You can also try out https://structurizr.com/json to see how this workspace will be rendered.
# Why use `buildzr`?
✅ Uses fluent APIs to help you create C4 model architecture diagrams in Python concisely.
✅ Write Structurizr diagrams more securely with extensive type hints and [mypy](https://mypy-lang.org) support.
✅ Stays true to the [Structurizr JSON schema](https://mypy-lang.org/) standards. `buildzr` uses the [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator) to automatically generate the "low-level" [representation](buildzr/models/models.py) of the Workspace model. This reduces deprecancy between `buildzr` and the Structurizr JSON schema.
✅ Writing architecture diagrams in Python allows you to integrate programmability and automation into your software architecture diagramming and documentation workflow.
✅ Uses the familiar Python programming language to write software architecture diagrams!
# Contributing
Interested in contributing to `buildzr`?
Please visit [CONTRIBUTING.md](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "buildzr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "architecture, buildzr, c4model, design, diagram, structurizr",
"author": null,
"author_email": "Amirul Menjeni <amirulmenjeni@pm.me>",
"download_url": "https://files.pythonhosted.org/packages/df/e7/646b7b215eccf102fc3953325ae64643a50660fd0174d33ec3c6daaa3a0c/buildzr-0.0.6.tar.gz",
"platform": null,
"description": "# Structurizr for the `buildzr`s \ud83e\uddf1\u2692\ufe0f\n\n`buildzr` is a [Structurizr](https://structurizr.com/) authoring tool for Python programmers.\n\nIf you're not familiar with Structurizr, it is both an open standard (see [Structurizr JSON schema](https://github.com/structurizr/json)) and a [set of tools](https://docs.structurizr.com/usage) for building software architecture diagrams as code. Structurizr derive its architecture modeling paradigm based on the [C4 model](https://c4model.com/), the modeling language for visualizing software architecture.\n\n`buildzr` offers flexible and fluent APIs to write software architecture models,\nleveraging the standard Structurizr JSON schema for interoperability with\nvarious rendering and authoring tools.\n\n# Quick Start \ud83d\ude80\n\n## Installation\n\nYou can use `pip` to install the `buildzr` package:\n\n```bash\npip install buildzr\n```\n\n## Creating a workspace\n\nThe module `buildzr.dsl` contains all the classes you need to create a workspace containing all the architecture models.\n\nBelow is an example, where we:\n1. Create the models (`Person`, `SoftwareSystem`s, the `Container`s inside the `SoftwareSystem`, and the relationships between them)\n2. Define multiple views using the models we've created before.\n\n```python\nimport os\nimport json\n\nfrom buildzr.encoders import JsonEncoder\n\nfrom buildzr.dsl import (\n Workspace,\n SoftwareSystem,\n Person,\n Container,\n SystemContextView,\n ContainerView,\n desc,\n Group,\n)\n\nw = Workspace('w')\\\n .contains(\n Group(\n \"My Company\",\n Person('Web Application User').labeled('u'),\n SoftwareSystem('Corporate Web App').labeled('webapp')\n .contains(\n Container('database'),\n Container('api'),\n )\\\n .where(lambda s: [\n s.api >> \"Reads and writes data from/to\" >> s.database,\n ])\n ),\n Group(\n \"Microsoft\",\n SoftwareSystem('Microsoft 365').labeled('email_system'),\n )\n )\\\n .where(lambda w: [\n w.person().u >> [\n desc(\"Reads and writes email using\") >> w.software_system().email_system,\n desc(\"Create work order using\") >> w.software_system().webapp,\n ],\n w.software_system().webapp >> \"sends notification using\" >> w.software_system().email_system,\n ])\\\n .with_views(\n SystemContextView(\n lambda w: w.software_system().webapp,\n key='web_app_system_context_00',\n description=\"Web App System Context\",\n auto_layout='lr',\n exclude_elements=[\n lambda w, e: w.person().user == e,\n ]\n ),\n ContainerView(\n lambda w: w.software_system().webapp,\n key='web_app_container_view_00',\n auto_layout='lr',\n description=\"Web App Container View\",\n )\n )\\\n .get_workspace()\n\n# Save workspace to a JSON file following the Structurizr JSON schema.\nw.to_json('workspace.json')\n```\n\nHere's a short breakdown on what's happening:\n- In `Workspace(...).contains(...)` method, we define the _static_ C4 models (i.e., `Person`, `SoftwareSystem`, and the `Container`s in the software system).\n- In the `Workspace(...).contains(...).where(...)`, we define the relationships between the C4 models in the workspace. We access the models via the `w` parameter in the `lambda` function, and create the relationships using the `>>` operators.\n- Once we have all the models and their relationships defined, we use (and re-use!) the static models to create multiple views to tell different stories and show various narrative to help document your software architecture.\n- Finally, we write the workspace definitions into a JSON file, which can be consumed by rendering tools, or used for further processing.\n\nThe JSON output can be found [here](examples/system_context_and_container_view.json). You can also try out https://structurizr.com/json to see how this workspace will be rendered.\n\n# Why use `buildzr`?\n\n\u2705 Uses fluent APIs to help you create C4 model architecture diagrams in Python concisely.\n\n\u2705 Write Structurizr diagrams more securely with extensive type hints and [mypy](https://mypy-lang.org) support.\n\n\u2705 Stays true to the [Structurizr JSON schema](https://mypy-lang.org/) standards. `buildzr` uses the [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator) to automatically generate the \"low-level\" [representation](buildzr/models/models.py) of the Workspace model. This reduces deprecancy between `buildzr` and the Structurizr JSON schema.\n\n\u2705 Writing architecture diagrams in Python allows you to integrate programmability and automation into your software architecture diagramming and documentation workflow.\n\n\u2705 Uses the familiar Python programming language to write software architecture diagrams!\n\n# Contributing\n\nInterested in contributing to `buildzr`?\n\nPlease visit [CONTRIBUTING.md](CONTRIBUTING.md).",
"bugtrack_url": null,
"license": null,
"summary": "Structurizr for the `buildzr`s \ud83e\uddf1\u2692\ufe0f",
"version": "0.0.6",
"project_urls": {
"homepage": "https://github.com/amirulmenjeni/buildzr",
"issues": "https://github.com/amirulmenjeni/buildzr/issues"
},
"split_keywords": [
"architecture",
" buildzr",
" c4model",
" design",
" diagram",
" structurizr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f56b2c7203e7d1c40f61674ffe0502fa66fa03b2f17d0101f50add85ed2a74d9",
"md5": "22b09e497f5f91ba864769298a7f5d10",
"sha256": "0c411e1f122dd859aebc8a719ffe95637ce02bfec450fc69cfe89ed005a1931f"
},
"downloads": -1,
"filename": "buildzr-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22b09e497f5f91ba864769298a7f5d10",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26898,
"upload_time": "2024-11-11T13:14:14",
"upload_time_iso_8601": "2024-11-11T13:14:14.268571Z",
"url": "https://files.pythonhosted.org/packages/f5/6b/2c7203e7d1c40f61674ffe0502fa66fa03b2f17d0101f50add85ed2a74d9/buildzr-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dfe7646b7b215eccf102fc3953325ae64643a50660fd0174d33ec3c6daaa3a0c",
"md5": "03e3d17f5051944d1fd01ee1ebd2273b",
"sha256": "ac80883d959039586dd0b07eb3235a11209cf6b9c403c4d22c8b5d656b0e7590"
},
"downloads": -1,
"filename": "buildzr-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "03e3d17f5051944d1fd01ee1ebd2273b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35089,
"upload_time": "2024-11-11T13:14:15",
"upload_time_iso_8601": "2024-11-11T13:14:15.949521Z",
"url": "https://files.pythonhosted.org/packages/df/e7/646b7b215eccf102fc3953325ae64643a50660fd0174d33ec3c6daaa3a0c/buildzr-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-11 13:14:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "amirulmenjeni",
"github_project": "buildzr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "buildzr"
}
JSON
