pacta 0.0.3

A Python tool for enforcing and visualizing software architecture.

Architecture Governance & Architecture-as-Code

PyPI • Docs • Issues

---

Warning: Experimental. Expect breaking changes until release 0.1.0

Pacta is an architecture governance tool that helps teams define architectural intent, gain insights through metrics and historical trends, detect architectural drift, and evolve codebases safely without blocking delivery.

pip install pacta

Supported languages:

• Python
• Java (coming soon)
• Go (coming soon)
• C# (coming soon)

Why?

Codebases rot. Architecture degrades through small changes no one tracks. Pacta turns architecture into something measurable, reviewable, and enforceable — catching drift early, not months later.

What it does

• Static analysis — parses Python AST, builds a system graph
• Layer enforcement — domain can't import from infra, etc.
• Snapshots — version your architecture like code
• Baseline mode — fail only on new violations, not legacy debt
• History tracking — view architecture evolution over time
• Trend analysis — track violations, nodes, edges over time with charts

Quick example

This is a minimal example. See the docs for advanced rules, baselines, and history.

Define your layers in architecture.yml:

version: 1
system:
  id: myapp
  name: My App

containers:
  backend:
    code:
      roots: [src]
      layers:
        domain:
          patterns: [src/domain/**]
        infra:
          patterns: [src/infra/**]

Add rules in rules.pacta.yml:

rule:
  id: no_domain_to_infra
  name: Domain cannot depend on Infrastructure
  severity: error
  target: dependency
  when:
    all:
      - from.layer == domain
      - to.layer == infra
  action: forbid
  message: Domain layer must not import from Infrastructure

Run it:

$ pacta scan . --model architecture.yml --rules rules.pacta.yml

✗ 2 violations (2 error) [2 new]
  ✗ ERROR [no_domain_to_infra] Domain cannot depend on Infrastructure @ src/domain/user.py:3:1
    status: new
    Domain layer must not import from Infrastructure

Baseline workflow

Got legacy violations? Save a baseline and only fail on new ones:

# Save current state
pacta scan . --model architecture.yml --rules rules.pacta.yml --save-ref baseline

# Later, in CI — fail only on new violations
pacta scan . --model architecture.yml --rules rules.pacta.yml --baseline baseline

History tracking

Every scan creates a content-addressed snapshot. Inspect how your architecture evolves over time:

# View timeline
$ pacta history show --last 5

# View trends over time (violations, nodes, edges, coupling)
$ pacta history trends .

Docs

• CLI Reference
• Architecture Model
• Rules DSL

Roadmap (short)

• Open-source CLI and analysis engine
• Content-addressed snapshots with history tracking
• Trend analysis with chart export
• Architecture visualization (Mermaid, D2)
• Health metrics (drift score, instability)
• Optional hosted service (future):
  • Cross-repository insights
  • Historical trend analysis
  • Team-level governance and reporting

License

Apache-2.0. See LICENSE.