Architecture Overview

Note

πŸ”§ Intermediate / Architecture β€” Understand how pyArchimate is organized and where to hook in your own custom readers, writers, and validators.

Package Structure

PyArchimate is organized into functional packages, each with a specific responsibility:

pyArchimate

Main package. Provides the public API through the shim module pyArchimate.pyArchimate, which re-exports all commonly-used classes and enums.

pyArchimate.model

Core data structures. Contains Model, Element, Relationship, View, Node, and Connection classes that form the in-memory representation of an ArchiMate model.

pyArchimate.element / pyArchimate.relationship

Type definitions. ArchiType and RelationType enums define all supported element and relationship types per the ArchiMate specification.

pyArchimate.readers

Import implementations. Contains reader classes for different file formats:

  • archimateReader β€” Native ArchiMate XML format (.archimate)

  • openGroupReader β€” OpenGroup XML exchange format

  • Custom readers can be registered for new formats

pyArchimate.writers

Export implementations. Contains writer classes for different output formats:

  • archiWriter β€” Write to native ArchiMate XML format

  • archimateWriter β€” Alternative ArchiMate XML writer

  • Custom writers can be registered for new formats

pyArchimate.validation

Model validation. Contains rules and validators for checking model consistency:

  • check_valid_relationship β€” Validate that a relationship type is allowed between two element types

  • checker_rules.yml β€” Configuration file defining what element types are valid in which layers and viewpoints

pyArchimate.viewpoint

Viewpoint definitions. Contains standard ArchiMate viewpoint definitions (Business Process, Application Structure, Technology, etc.) and utilities for filtering elements by viewpoint.

pyArchimate.helpers

Utility functions. Shared utilities for working with models, elements, and relationships (hierarchy operations, property management, etc.).

Layered Dependencies

The architecture follows a layered dependency model:

  1. Core Layer: model, element, relationship β€” fundamental data structures with no external dependencies beyond lxml for XML handling.

  2. Validation Layer: validation β€” builds on core layer to enforce business rules and type constraints.

  3. Transformation Layer: readers, writers β€” builds on core layer to parse and generate file formats.

  4. Public API Layer: pyArchimate (shim) β€” re-exports commonly-used classes and enums for convenience.

Each layer is independent, allowing you to:

  • Use the core model in your own custom tools

  • Replace the validation layer with custom rules

  • Add new readers and writers without modifying existing code

Architecture Diagrams

The following diagrams illustrate pyArchimate’s architecture from different perspectives:

The files in docs/diagrams are PlantUML sources that document the architecture of pyArchimate. They include both classic UML views (class, component, object, deployment, etc.) and derived C4-style diagrams that illustrate how the project is composed.

Available diagrams:

The rendered PNG artifacts live next to the PlantUML sources (docs/diagrams/*.png) and are overwritten each time you run scripts/render_diagrams.sh. Including them in the docs allows the website to display the diagrams without requiring a PlantUML renderer on the client side.

context.puml / c4_context.puml

Context diagram showing how pyArchimate integrates with external tooling, developers, and the ArchiMate standard.

Context diagram showing the integration points with external tooling, developers, and the ArchiMate standard. Context diagram showing the integration points with external tooling, developers, and the ArchiMate standard.
package.puml / c4_container.puml

Container diagram showing how pyArchimate integrates with external tooling, developers, and the ArchiMate standard.

Container diagram showing the deployment structure of pyArchimate. Package diagram showing the modular structure of the pyArchimate project.
component.puml / c4_component.puml

Component diagrams that highlight the major modules such as the model core, readers, and writers.

Component diagram showing the major modules of pyArchimate. Component diagram showing the major modules of pyArchimate.
deployment.puml / c4_deployment.puml

Deployment diagrams describing the runtime environment, processing steps, and how the PlantUML renderer/slim server might be hosted.

Deployment diagram showing the runtime environment and processing steps. Deployment diagram showing the runtime environment and processing steps.
class.puml / object.puml / composite.puml

UML views that sketch the static structure of Model, Element, Relationship, and the associated helper utilities.

Class diagram showing Model, Element, Relationship, View, Node, and Connection relationships. Object diagram showing the dynamic interactions between instances of the classes. Composite structure diagram showing the internal structure of complex elements.
state.puml

State diagram illustrating the Model lifecycle as it moves from empty through populated, view ready, serialized, and invalid states when validations fail.

State diagram for Model lifecycle transitions.
sequence.puml

Sequence diagram depicting how the CLI/script invokes Model.read, how readers populate Elements/Relationships, and how writers serialize the resulting model.

Sequence diagram showing the reader/writer interactions during a Model read/write cycle.
activity.puml

Activity diagram of view construction: creating models, adding elements/relationships, building views, and writing outputs.

Activity diagram describing the view construction workflow.
communication.puml

Communication diagram showing runtime message paths between Model, Element, Relationship, View, Node, and Connection during CRUD operations.

Communication diagram showing the collaboration of Model, View, Node, and Connection.

Rendering Diagrams

To regenerate the PNG artifacts locate the PlantUML renderer and run the helper script:

` ./scripts/render_diagrams.sh `

The script encodes every PlantUML source, hits ${PLANTUML_SERVER:-https://www.plantuml.com/plantuml}, follows redirects, and retries slow transfers so the loop can finish. Set PLANTUML_SERVER if you want to target a different host (for example export PLANTUML_SERVER=http://host.containers.internal:8080), otherwise it defaults to the public PlantUML service.

If you add or refactor diagrams, update this document with a short explanation of the new view and add the source file to the script so it continues to be rendered automatically.

Extension Points

PyArchimate is designed to be extended. The following sections explain where and how to add custom functionality.

Custom Readers

To add support for a new import format, create a reader class and register it in the MODEL_READER_REGISTRY:

from pyArchimate.readers import MODEL_READER_REGISTRY

class CustomReader:
    def read(self, filepath):
        # Parse file and return a Model instance
        pass

MODEL_READER_REGISTRY['custom'] = CustomReader()

For detailed examples and patterns, see Extending pyArchimate.

Custom Writers

To add support for a new export format, extend the Writers enum and implement a writer class:

from pyArchimate.writers import Writers

class CustomWriter:
    def write(self, model, filepath):
        # Serialize model to file
        pass

For detailed examples and patterns, see Extending pyArchimate.

Custom Validation Rules

You can extend model validation by adding custom rules to checker_rules.yml or by programmatically validating models using the public API.

For details, see Extending pyArchimate.