julee-c4 0.1.0__py3-none-any.whl

julee_c4/__init__.py

@@ -0,0 +1,26 @@
+"""C4 architecture models.
+
+A julee kit. It holds the C4 model — software systems, containers,
+components, the relationships between them, deployment nodes and dynamic
+steps — and the queries that assemble those into the six C4 diagrams.
+
+It describes how a system is built rather than what business it is in, so
+it carries no domain of its own. julee-viewpoints renders what a solution
+declares here into its documentation.
+
+Install it, then adopt it::
+
+    [tool.julee]
+    kits = ["c4"]
+"""
+
+from julee.core.entities.kit import Kit
+
+kit = Kit(
+    slug="c4",
+    name="C4 architecture models",
+    package="julee_c4",
+    viewpoint=True,
+)
+
+__all__ = ["kit"]

julee_c4/domain/models/__init__.py

@@ -0,0 +1,11 @@
+"""C4 domain entities.
+
+Import directly from submodules:
+    from julee_c4.domain.models.software_system import SoftwareSystem, SystemType
+    from julee_c4.domain.models.container import Container, ContainerType
+    from julee_c4.domain.models.component import Component
+    from julee_c4.domain.models.relationship import Relationship, ElementType
+    from julee_c4.domain.models.deployment_node import DeploymentNode, NodeType
+    from julee_c4.domain.models.dynamic_step import DynamicStep
+    from julee_c4.domain.models.diagrams import SystemContextDiagram, ContainerDiagram, ...
+"""

julee_c4/domain/models/component.py

@@ -0,0 +1,101 @@
+"""Component domain model.
+
+A grouping of related functionality within a container.
+"""
+
+from julee.core.entities.entity import Entity
+from julee.core.utils import normalize_name, slugify
+from pydantic import Field, computed_field, field_validator
+
+
+class Component(Entity):
+    """Component entity.
+
+    A component is a grouping of related functionality encapsulated
+    behind a well-defined interface. Components exist within containers
+    and are NOT separately deployable units.
+    """
+
+    slug: str
+    name: str
+    container_slug: str
+    system_slug: str
+    description: str = ""
+    technology: str = ""
+    interface: str = ""
+    code_path: str = ""
+    tags: tuple[str, ...] = Field(default_factory=tuple)
+    docname: str = ""
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate and normalize slug."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return slugify(v.strip())
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @field_validator("container_slug", mode="before")
+    @classmethod
+    def validate_container_slug(cls, v: str) -> str:
+        """Validate container_slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("container_slug cannot be empty")
+        return v.strip()
+
+    @field_validator("system_slug", mode="before")
+    @classmethod
+    def validate_system_slug(cls, v: str) -> str:
+        """Validate system_slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("system_slug cannot be empty")
+        return v.strip()
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def name_normalized(self) -> str:
+        """Normalized name for case-insensitive matching."""
+        return normalize_name(self.name)
+
+    @property
+    def qualified_slug(self) -> str:
+        """Fully qualified slug including container and system."""
+        return f"{self.system_slug}/{self.container_slug}/{self.slug}"
+
+    @property
+    def has_code(self) -> bool:
+        """Check if component has linked code."""
+        return bool(self.code_path)
+
+    @property
+    def has_interface(self) -> bool:
+        """Check if component has interface description."""
+        return bool(self.interface)
+
+    def has_tag(self, tag: str) -> bool:
+        """Check if component has a specific tag (case-insensitive)."""
+        return tag.lower() in [t.lower() for t in self.tags]
+
+    def with_tag(self, tag: str) -> "Component":
+        """The entity with a tag added.
+
+        An entity is immutable, so this returns a new one rather than
+        changing this one. A tag already present is not added twice.
+
+        Args:
+            tag: Tag to add
+
+        Returns:
+            A new Component, or this one if it already had the tag
+        """
+        if self.has_tag(tag):
+            return self
+        return self.model_copy(update={"tags": (*self.tags, tag)})

julee_c4/domain/models/container.py

@@ -0,0 +1,121 @@
+"""Container domain model.
+
+A runtime boundary - application or data store within a software system.
+"""
+
+from enum import StrEnum
+
+from julee.core.entities.entity import Entity
+from julee.core.utils import normalize_name, slugify
+from pydantic import Field, computed_field, field_validator
+
+
+class ContainerType(StrEnum):
+    """Classification of containers."""
+
+    WEB_APPLICATION = "web_application"
+    MOBILE_APP = "mobile_app"
+    DESKTOP_APP = "desktop_app"
+    CONSOLE_APP = "console_app"
+    SERVERLESS_FUNCTION = "serverless_function"
+    DATABASE = "database"
+    FILE_STORAGE = "file_storage"
+    MESSAGE_QUEUE = "message_queue"
+    API = "api"
+    OTHER = "other"
+
+
+class Container(Entity):
+    """Container entity.
+
+    A container is an application or data store - a runtime boundary.
+    Something that needs to be running for the overall system to work.
+
+    Note: This has nothing to do with Docker. The term "container" in C4
+    predates containerization technology.
+    """
+
+    slug: str
+    name: str
+    system_slug: str
+    description: str = ""
+    container_type: ContainerType = ContainerType.OTHER
+    technology: str = ""
+    url: str = ""
+    tags: tuple[str, ...] = Field(default_factory=tuple)
+    docname: str = ""
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate and normalize slug."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return slugify(v.strip())
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @field_validator("system_slug", mode="before")
+    @classmethod
+    def validate_system_slug(cls, v: str) -> str:
+        """Validate system_slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("system_slug cannot be empty")
+        return v.strip()
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def name_normalized(self) -> str:
+        """Normalized name for case-insensitive matching."""
+        return normalize_name(self.name)
+
+    @property
+    def qualified_slug(self) -> str:
+        """Fully qualified slug including system."""
+        return f"{self.system_slug}/{self.slug}"
+
+    @property
+    def is_data_store(self) -> bool:
+        """Check if this container stores data."""
+        return self.container_type in [
+            ContainerType.DATABASE,
+            ContainerType.FILE_STORAGE,
+        ]
+
+    @property
+    def is_application(self) -> bool:
+        """Check if this container is an application."""
+        return self.container_type in [
+            ContainerType.WEB_APPLICATION,
+            ContainerType.MOBILE_APP,
+            ContainerType.DESKTOP_APP,
+            ContainerType.CONSOLE_APP,
+            ContainerType.SERVERLESS_FUNCTION,
+            ContainerType.API,
+        ]
+
+    def has_tag(self, tag: str) -> bool:
+        """Check if container has a specific tag (case-insensitive)."""
+        return tag.lower() in [t.lower() for t in self.tags]
+
+    def with_tag(self, tag: str) -> "Container":
+        """The entity with a tag added.
+
+        An entity is immutable, so this returns a new one rather than
+        changing this one. A tag already present is not added twice.
+
+        Args:
+            tag: Tag to add
+
+        Returns:
+            A new Container, or this one if it already had the tag
+        """
+        if self.has_tag(tag):
+            return self
+        return self.model_copy(update={"tags": (*self.tags, tag)})

julee_c4/domain/models/deployment_node.py

@@ -0,0 +1,175 @@
+"""DeploymentNode domain model.
+
+Infrastructure where containers are deployed.
+"""
+
+from collections.abc import Mapping
+from enum import StrEnum
+
+from julee.core.entities.entity import Entity
+from julee.core.utils import slugify
+from pydantic import Field, field_validator
+
+
+class NodeType(StrEnum):
+    """Classification of deployment nodes."""
+
+    PHYSICAL_SERVER = "physical_server"
+    VIRTUAL_MACHINE = "virtual_machine"
+    CONTAINER_RUNTIME = "container_runtime"  # Docker, containerd, etc.
+    KUBERNETES_CLUSTER = "kubernetes_cluster"
+    KUBERNETES_POD = "kubernetes_pod"
+    CLOUD_REGION = "cloud_region"
+    AVAILABILITY_ZONE = "availability_zone"
+    BROWSER = "browser"
+    MOBILE_DEVICE = "mobile_device"
+    DNS = "dns"
+    LOAD_BALANCER = "load_balancer"
+    FIREWALL = "firewall"
+    CDN = "cdn"
+    OTHER = "other"
+
+
+class ContainerInstance(Entity):
+    """A deployed instance of a container.
+
+    Represents a container running within a deployment node.
+    """
+
+    container_slug: str
+    instance_count: int = 1
+    properties: Mapping[str, str] = Field(default_factory=dict)
+
+    @field_validator("container_slug", mode="before")
+    @classmethod
+    def validate_container_slug(cls, v: str) -> str:
+        """Validate container_slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("container_slug cannot be empty")
+        return v.strip()
+
+
+class DeploymentNode(Entity):
+    """DeploymentNode entity.
+
+    Represents infrastructure where containers run - physical servers,
+    VMs, Docker hosts, Kubernetes clusters, execution environments, etc.
+
+    Deployment nodes can be nested to represent infrastructure hierarchy
+    (e.g., Cloud Region > Availability Zone > Kubernetes Cluster > Pod).
+    """
+
+    slug: str
+    name: str
+    environment: str = "production"
+    node_type: NodeType = NodeType.OTHER
+    description: str = ""
+    technology: str = ""
+    instances: int = 1
+    parent_slug: str | None = None
+    container_instances: tuple[ContainerInstance, ...] = Field(default_factory=tuple)
+    properties: Mapping[str, str] = Field(default_factory=dict)
+    tags: tuple[str, ...] = Field(default_factory=tuple)
+    docname: str = ""
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate and normalize slug."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return slugify(v.strip())
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @property
+    def has_parent(self) -> bool:
+        """Check if this node has a parent node."""
+        return self.parent_slug is not None
+
+    @property
+    def has_containers(self) -> bool:
+        """Check if this node has deployed containers."""
+        return len(self.container_instances) > 0
+
+    @property
+    def total_container_instances(self) -> int:
+        """Get total count of container instances."""
+        return sum(ci.instance_count for ci in self.container_instances)
+
+    def deploys_container(self, container_slug: str) -> bool:
+        """Check if a specific container is deployed here."""
+        return any(
+            ci.container_slug == container_slug for ci in self.container_instances
+        )
+
+    def with_container_instance(
+        self,
+        container_slug: str,
+        instance_count: int = 1,
+        properties: Mapping[str, str] | None = None,
+    ) -> "DeploymentNode":
+        """The node with a container deployed on it.
+
+        Deploying a container that is already here adds to its count and
+        merges its properties, rather than listing it twice. An entity is
+        immutable, so this returns a new node.
+
+        Args:
+            container_slug: Container being deployed
+            instance_count: How many of it
+            properties: Deployment properties, merged with any already set
+
+        Returns:
+            A new DeploymentNode
+        """
+        instances = []
+        found = False
+        for instance in self.container_instances:
+            if instance.container_slug == container_slug:
+                found = True
+                instances.append(
+                    instance.model_copy(
+                        update={
+                            "instance_count": instance.instance_count + instance_count,
+                            "properties": {**instance.properties, **(properties or {})},
+                        }
+                    )
+                )
+            else:
+                instances.append(instance)
+        if not found:
+            instances.append(
+                ContainerInstance(
+                    container_slug=container_slug,
+                    instance_count=instance_count,
+                    properties=properties or {},
+                )
+            )
+        return self.model_copy(update={"container_instances": tuple(instances)})
+
+    def has_tag(self, tag: str) -> bool:
+        """Check if node has a specific tag (case-insensitive)."""
+        return tag.lower() in [t.lower() for t in self.tags]
+
+    def with_tag(self, tag: str) -> "DeploymentNode":
+        """The entity with a tag added.
+
+        An entity is immutable, so this returns a new one rather than
+        changing this one. A tag already present is not added twice.
+
+        Args:
+            tag: Tag to add
+
+        Returns:
+            A new DeploymentNode, or this one if it already had the tag
+        """
+        if self.has_tag(tag):
+            return self
+        return self.model_copy(update={"tags": (*self.tags, tag)})

julee_c4/domain/models/diagrams.py

@@ -0,0 +1,106 @@
+"""C4 Diagram domain models.
+
+These models represent the computed data for various C4 diagram types.
+They are domain objects that can be serialized to different output formats
+(PlantUML, Structurizr DSL, etc.) by serializers.
+"""
+
+from julee.core.entities.entity import Entity
+from pydantic import Field
+
+from .component import Component
+from .container import Container
+from .deployment_node import DeploymentNode
+from .dynamic_step import DynamicStep
+from .relationship import Relationship
+from .software_system import SoftwareSystem
+
+
+class PersonInfo(Entity):
+    """Minimal person info for diagrams.
+
+    Represents a user/actor in C4 diagrams. This is a lightweight
+    representation used when full Person entities aren't needed.
+    """
+
+    slug: str
+    name: str
+    description: str = ""
+
+
+class SystemLandscapeDiagram(Entity):
+    """Domain model for a C4 System Landscape diagram.
+
+    Shows all software systems and their relationships at the highest level.
+    """
+
+    systems: tuple[SoftwareSystem, ...] = Field(default_factory=tuple)
+    person_slugs: tuple[str, ...] = Field(default_factory=tuple)
+    relationships: tuple[Relationship, ...] = Field(default_factory=tuple)
+
+
+class SystemContextDiagram(Entity):
+    """Domain model for a C4 System Context diagram.
+
+    Shows a single system in context with its users and external systems.
+    """
+
+    system: SoftwareSystem
+    external_systems: tuple[SoftwareSystem, ...] = Field(default_factory=tuple)
+    person_slugs: tuple[str, ...] = Field(default_factory=tuple)
+    persons: tuple[PersonInfo, ...] = Field(default_factory=tuple)
+    relationships: tuple[Relationship, ...] = Field(default_factory=tuple)
+
+
+class ContainerDiagram(Entity):
+    """Domain model for a C4 Container diagram.
+
+    Shows the containers within a software system.
+    """
+
+    system: SoftwareSystem
+    containers: tuple[Container, ...] = Field(default_factory=tuple)
+    external_systems: tuple[SoftwareSystem, ...] = Field(default_factory=tuple)
+    person_slugs: tuple[str, ...] = Field(default_factory=tuple)
+    relationships: tuple[Relationship, ...] = Field(default_factory=tuple)
+
+
+class ComponentDiagram(Entity):
+    """Domain model for a C4 Component diagram.
+
+    Shows the components within a container.
+    """
+
+    system: SoftwareSystem
+    container: Container
+    components: tuple[Component, ...] = Field(default_factory=tuple)
+    external_containers: tuple[Container, ...] = Field(default_factory=tuple)
+    external_systems: tuple[SoftwareSystem, ...] = Field(default_factory=tuple)
+    person_slugs: tuple[str, ...] = Field(default_factory=tuple)
+    relationships: tuple[Relationship, ...] = Field(default_factory=tuple)
+
+
+class DeploymentDiagram(Entity):
+    """Domain model for a C4 Deployment diagram.
+
+    Shows the deployment infrastructure for an environment.
+    """
+
+    environment: str
+    nodes: tuple[DeploymentNode, ...] = Field(default_factory=tuple)
+    containers: tuple[Container, ...] = Field(default_factory=tuple)
+    relationships: tuple[Relationship, ...] = Field(default_factory=tuple)
+
+
+class DynamicDiagram(Entity):
+    """Domain model for a C4 Dynamic diagram.
+
+    Shows a sequence of interactions for a specific scenario.
+    """
+
+    sequence_name: str
+    steps: tuple[DynamicStep, ...] = Field(default_factory=tuple)
+    systems: tuple[SoftwareSystem, ...] = Field(default_factory=tuple)
+    containers: tuple[Container, ...] = Field(default_factory=tuple)
+    components: tuple[Component, ...] = Field(default_factory=tuple)
+    person_slugs: tuple[str, ...] = Field(default_factory=tuple)

julee_c4/domain/models/dynamic_step.py

@@ -0,0 +1,116 @@
+"""DynamicStep domain model.
+
+A numbered step in a dynamic (sequence) diagram.
+"""
+
+from julee.core.entities.entity import Entity
+from julee.core.utils import slugify
+from pydantic import field_validator
+
+from .relationship import ElementType
+
+
+class DynamicStep(Entity):
+    """DynamicStep entity.
+
+    Represents a numbered interaction in a dynamic diagram.
+    Dynamic diagrams show runtime behavior for specific scenarios
+    (user stories, use cases, features).
+    """
+
+    slug: str = ""
+    sequence_name: str
+    step_number: int
+    source_type: ElementType
+    source_slug: str
+    destination_type: ElementType
+    destination_slug: str
+    description: str = ""
+    technology: str = ""
+    return_value: str = ""
+    is_async: bool = False
+    docname: str = ""
+
+    def model_post_init(self, __context: object) -> None:
+        """Derive the slug when none was given.
+
+        A step is identified by where it sits in its sequence, which the
+        step already knows, so the slug is derivable rather than required.
+        """
+        if not self.slug:
+            object.__setattr__(
+                self, "slug", self.generate_slug(self.sequence_name, self.step_number)
+            )
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Normalise the slug; an empty one is derived after validation."""
+        return v.strip() if v else v
+
+    @field_validator("sequence_name", mode="before")
+    @classmethod
+    def validate_sequence_name(cls, v: str) -> str:
+        """Validate sequence_name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("sequence_name cannot be empty")
+        return v.strip()
+
+    @field_validator("step_number")
+    @classmethod
+    def validate_step_number(cls, v: int) -> int:
+        """Validate step_number is positive."""
+        if v < 1:
+            raise ValueError("step_number must be >= 1")
+        return v
+
+    @field_validator("source_slug", mode="before")
+    @classmethod
+    def validate_source_slug(cls, v: str) -> str:
+        """Validate source_slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("source_slug cannot be empty")
+        return v.strip()
+
+    @field_validator("destination_slug", mode="before")
+    @classmethod
+    def validate_destination_slug(cls, v: str) -> str:
+        """Validate destination_slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("destination_slug cannot be empty")
+        return v.strip()
+
+    @property
+    def step_label(self) -> str:
+        """Get formatted step label (e.g., '1. ')."""
+        return f"{self.step_number}. "
+
+    @property
+    def full_label(self) -> str:
+        """Get full step label with description."""
+        base = f"{self.step_number}. {self.description}"
+        if self.technology:
+            base = f"{base} [{self.technology}]"
+        return base
+
+    @property
+    def is_person_interaction(self) -> bool:
+        """Check if this step involves a person."""
+        return (
+            self.source_type == ElementType.PERSON
+            or self.destination_type == ElementType.PERSON
+        )
+
+    @classmethod
+    def generate_slug(cls, sequence_name: str, step_number: int) -> str:
+        """Generate slug from sequence and step number."""
+        return f"{slugify(sequence_name)}-step-{step_number}"
+
+    def involves_element(self, element_type: ElementType, element_slug: str) -> bool:
+        """Check if step involves a specific element."""
+        return (
+            self.source_type == element_type and self.source_slug == element_slug
+        ) or (
+            self.destination_type == element_type
+            and self.destination_slug == element_slug
+        )