Skip to content

Contracts and Boundaries

Atlas relies on boundaries to keep the codebase teachable and contracts to keep stable promises explicit.

Boundary Model

flowchart LR
    Contracts[Contracts] --> APIs[API schemas]
    Contracts --> Configs[Runtime config]
    Contracts --> Errors[Errors and outputs]
    Domain[Domain] --> App[App]
    App --> Adapters[Adapters]
    Runtime[Runtime] --> App
    Runtime --> Adapters

This boundary model shows the relationship between code placement and stable promises. Contracts define what outside consumers can rely on, while the architectural layers decide where behavior should live internally.

Contract Purpose

flowchart TD
    Contract[Contract] --> Promise[Stable promise]
    Promise --> Docs[Documentation]
    Promise --> Tests[Compatibility tests]
    Promise --> Release[Release confidence]

This contract-purpose diagram exists so maintainers remember that a contract is more than a page in the docs. It should connect documentation, enforcement, and release confidence.

The Main Architectural Idea

Boundaries decide where code should live.

Contracts decide what the outside world can rely on.

Those are related, but they are not the same thing.

Typical Failure Modes

  • duplicated contract ownership
  • broad barrels hiding the real source of truth
  • runtime or adapter logic bleeding into domain surfaces
  • undocumented helper paths becoming accidental API

Healthy Boundary Behavior

  • ownership is obvious from the tree
  • contracts have one owner path
  • compatibility is test-backed
  • internal refactors do not quietly redefine public promises

Two Questions That Prevent Drift

  • where should this code live?
  • what, if anything, should an outside consumer be able to rely on?

Those questions sound similar, but Atlas treats them differently on purpose.

Purpose

This page explains the Atlas material for contracts and boundaries and points readers to the canonical checked-in workflow or boundary for this topic.

Stability

This page is part of the canonical Atlas docs spine. Keep it aligned with the current repository behavior and adjacent contract pages.