Support Fractal Architecture Modeling (System → Service → Module → Layer → Library)

[akhundMurad]

Currently, Pacta architecture modeling feels focused on a single service or a flat structure.
In real-world systems, architecture is fractal: the same concepts repeat at different levels of scale.

This issue proposes introducing a fractal architecture model, where a Pacta project can describe:

• a whole system (or platform)
• multiple services (microservices or bounded contexts)
• modules inside services
• layers inside modules
• shared libraries as first-class architectural elements

All levels should use the same conceptual building blocks and rules.

Why this matters

• Enables Pacta to work with monorepos and microservice architectures
• Avoids forcing users to split architecture across multiple tools
• Makes Pacta applicable beyond “single-service” use cases

Acceptance Criteria

• Architecture model supports multiple hierarchy levels: system, service, module, layer, library
• Rules can be applied at any level (e.g. service-to-service, layer-to-layer)
• Libraries can be modeled independently or attached to services
• Architecture remains analyzable via CLI and CI

Out of scope

• Enterprise architecture layers (Business / Technology)
• Visual modeling UI

[akhundMurad]

Design / Implementation Plan — Schema v2

This issue introduces fractal architecture modeling in Pacta: the ability to describe services, modules, and libraries using a single recursive container model, while keeping full backward compatibility with existing v1 configurations.

The goal is to support:

• multi-service systems
• nested modules inside services
• shared libraries
• service-aware architecture rules

without introducing a separate modeling language or breaking existing users.

Core design decisions

• There is one architectural building block: Container

• Containers can be nested recursively via contains

• Each container has an explicit kind:

  • service
  • module
  • library

• The system root remains implicit (system:)

• Nested containers are flattened internally using dot-qualified IDs
  (billing-service.invoice-module)

• Rules and analysis continue to operate on a flat namespace

• v1 architecture files must continue to work unchanged

This is a schema and model evolution, not a rewrite.

Schema v2 (conceptual)

version: 2

system:
  id: my-platform
  name: My Platform

containers:
  billing-service:
    kind: service
    domain: billing
    code:
      roots: [services/billing]
      layers:
        api: [services/billing/api/**]
        domain: [services/billing/domain/**]
    contains:
      invoice-module:
        kind: module
        code:
          roots: [services/billing/domain/invoice]
          layers:
            model: [services/billing/domain/invoice/model/**]
            repo: [services/billing/domain/invoice/repo/**]

  shared-utils:
    kind: library
    code:
      roots: [libs/shared]

interactions:
  - from: billing-service
    to: shared-utils
    protocol: import

Notes:

• domain: is an alias for the existing context: key
• interactions: is an alias for the existing relations: key
• v1 files without contains or kind remain valid

Model changes

Container

• Add kind: str (service | module | library)
• Add children: Mapping[str, Container] populated from contains
• Add parent: str | None (resolved, not parsed)

ArchitectureModel

• Add containers_flat: Mapping[str, Container]

  • contains all containers, including nested ones
  • keys are dot-qualified IDs

• Existing APIs (get_container, all_container_ids) should use the flat map

Loader changes

• Support recursive parsing of contains
• Require kind for v2 containers
• Accept domain: as alias for context:
• Accept interactions: as alias for relations:
• v1 loader behavior remains unchanged

Resolver changes

• Recursively walk the container tree
• Build containers_flat using dot-qualified IDs
• Assign parent on child containers
• Child containers inherit parent domain unless explicitly overridden
• Populate code roots and layer patterns for all flattened containers

Validation rules

Validation becomes recursive and hierarchical:

• kind must be one of the supported values
• No duplicate IDs in the flattened namespace
• Child code.roots must be subpaths of the parent roots
• Validation errors must clearly reference the dot-qualified container ID

IR extensions

To enable service-level rules:

IRNode

• Add service: str | None

  • resolved as the top-level container ancestor

• Add container_kind: str | None

IREdge

• Add src_service, dst_service
• Add src_container_kind, dst_container_kind

All fields must be backward compatible in serialization.

Enrichment logic

• Match code paths against flattened containers

• Prefer the deepest match (most specific container)

• Set:

  • node.container → dot-qualified container ID
  • node.service → top-level ancestor ID

• Edge metadata mirrors node metadata

For v1 models, behavior remains unchanged.

Rules DSL changes

The DSL must expose service and container metadata explicitly.

New rule fields

Field	Meaning
node.service	Top-level service owning the node
node.kind	Container kind (service/module/library)
node.symbol_kind	Existing symbol kind (renamed from node.kind)
from.service, to.service	Edge service boundaries
from.kind, to.kind	Source/target container kind

Existing rules must continue to work without modification.

Example rules enabled by this change

# Forbid cross-service domain dependencies
rule:
  id: no-cross-service-domain-deps
  target: dependency
  action: forbid
  when:
    all:
      - from.service != to.service
      - from.layer == "domain"

# Libraries must not depend on services
rule:
  id: library-no-service-deps
  target: dependency
  action: forbid
  when:
    all:
      - from.kind == "library"
      - to.kind == "service"

Documentation and examples

• Add a new v2 microservices example using nested containers

• Document:

  • contains
  • kind
  • dot-qualified IDs
  • new rule fields

• Keep v1 documentation intact and valid

Verification

• All existing tests must pass unchanged
• v1 architecture files must produce identical results
• New example must load, enrich, and evaluate rules correctly

This change establishes the foundation for:

• service-aware rules
• cross-service architecture governance
• future runtime and interaction modeling

It intentionally does not introduce UI, enterprise layers, or runtime analysis.

[akhundMurad]

Areas need to be addressed before implementation begins.

1. Schema version detection and migration strategy

The plan references v2 but doesn't specify how version routing works at the loader level or how snapshots handle the transition.

Resolution:

Loader reads the version: key from YAML. Absent or 1 → v1 path. 2 → v2 path. Any other value → validation error with a clear message.

• v1 loader path is unchanged — no contains, no kind, existing keys only.
• v2 loader path parses contains:, kind:, and accepts the documented aliases.
• Bump ArchitectureIR.schema_version to 2 for snapshots produced with v2 models.
• from_dict() uses .get() with None defaults for all new IR fields, so v1 snapshots deserialize without error.
• Diffing across schema versions works because missing fields default to None on both sides.

This means old snapshots remain loadable and diffable against new ones without any migration step.

2. Interaction reference validation

The interactions: section references container IDs, but the plan doesn't mention validating that those IDs actually exist.

Resolution — add to validator (Step 4):

• All from: and to: values in interactions: must resolve to a container ID in the flat namespace (top-level or dot-qualified).
• On failure, emit a validation error listing the unknown ID and the set of available container IDs.

3. Immutable parent assignment on Container

Container should stay immutable. The plan says parent is "set by resolver" which implies post-construction mutation.

Resolution:

• The resolver creates new Container instances with parent populated at construction time. No field is mutated after creation. This preserves the frozen dataclass pattern used throughout the codebase.

4. containers_flat as a @property

Rather than storing containers_flat as a computed field on ArchitectureModel (which would require manual population and could drift), expose it as a @property that recursively walks containers and their children on access .get_container() and all_container_ids() delegate to it.

Everything else in the plan — the v1/v2 key aliases, dot-qualified IDs, IR field additions, rules DSL changes, node.kind rename, enrichment logic, and documentation structure — looks correct and ready to implement.