Bounded Software ArchitectureRead the guide

Vibe code today.
Keep it growing for years.

Code that changes together belongs together. An architecture heuristic for a smaller search space, explicit ownership, and predictable dependencies.

It started with Branch and Bound optimization technique. The spark for an architecture that keeps the search small as your codebase grows.

Explore the architecture

Built for developers. Legible to coding agents.

Ownership treeImports without cycles
Neutral lines show ownershipPrivate branch or sub-boundary → owner anchorCoordinator imports owned parts

Related architecture approaches

Across layers

Clean Architecture

Global technical layers can fragment a change. A folder layout can split one behavior across the application. BSA applies dependency discipline inside a recognizable domain owner.

Visible domain, verified connections

Vertical Slice Architecture / Screaming Architecture

Expose the domain. Then check the connections. Vertical slices keep a use case together; Screaming Architecture makes the application’s purpose visible. Neither organizing principle, on its own, verifies which components may connect. BSA makes those connections explicit and checks them against actual imports.

Start with one change.

  1. Name the owner

    Identify the module that owns the behavior you want to change.

  2. Choose the smallest home

    Keep local behavior with its owner. Put a shared domain concept at the smallest common owner.

  3. Make the connection explicit

    Use the intended audience surface and a declared import direction. Avoid cycles.

  4. Check the boundary

    Run focused tests and boundary checks to make sure the surfaces hold.

01

Colocate domain concepts that change together

Name boundaries after the business. Keep each concept, its rules, and related implementation with the owner of that concept.

02

Declare every connection

Say who may use each public surface and in which direction. Put coordination at the smallest owner that can connect the parts.

03

Verify the boundaries

Check actual imports against the declared connections. Reject private access and back-edges; test behavior through supported surfaces.

Organize ownership as a tree.
Keep imports free of cycles.

Each boundary owns a coherent responsibility and may contain smaller boundaries. Imports form a directed graph: modules can share anchors and connect different boundaries through declared surfaces, without cycles.

Meet Meridian, a fictional shipping company. Shipping exposes shipment.py and deliveries/ directly; deliveries own assignments and delays. Assignments use fleet’s public vehicle definitions. Fleet never imports shipping.

Meridian · a shipping company
  1. meridian/company boundary
  2. api.pyentry adapter
  3. cli.pyentry adapter
  4. worker.pyentry adapter
  5. fleet/boundary
  6. _commands/private branch
  7. commands.pypublic surface
  8. deps.pycoordinator
  9. http_routes.pyHTTP surface
  10. vehicle.pyanchor
  11. shipping/boundary
  12. _commands/private branch
  13. commands.pypublic surface
  14. deliveries/sub-boundary
  15. assignments/sub-boundary
  16. _commands/private branch
  17. assignment.pyanchor
  18. commands.pypublic surface
  19. commands.pypublic surface
  20. delays/sub-boundary
  21. _commands/private branch
  22. commands.pypublic surface
  23. delay_report.pyanchor
  24. delivery.pyanchor
  25. deps.pycoordinator
  26. http_routes.pyHTTP surface
  27. shipment.pyanchor

Shipping → fleet is the declared direction. Assignments own the relationship; deps.py composes it. Arrows are source imports, not execution.

Entry points together; domain contents alphabetical, with _commands/ first. Anchors keep values, contracts, and implementations together. Package __init__.py exports and shared HTTP support are omitted.

Boundary
Owns a coherent problem space and its supported surfaces. A sub-boundary has exactly one parent.
Anchor
The main domain concept of a boundary. Keep its types, invariants, and contracts close.
Private branch
Related implementation inside a boundary, such as _commands/. It belongs to that boundary and is accessed through the owner’s supported surface. Create a sub-boundary when the responsibility needs its own ownership.
Coordinator
Connects parts through supported surfaces in declared import directions. In Meridian, deps.py coordinates construction.
Surface
routes.py exposes HTTP; commands.py exposes commands. Package roots expose anchor vocabulary; private _commands/ implementations stay hidden.

Use these roles when needed. A small boundary can stay in one module; private branches and separate coordinators are optional.

Depend on anchors. Compose through coordinators.

Child conceptparent anchor

from meridian.shipping import ShipmentId

Coordinatorsub-boundary surface

from meridian.shipping.deliveries.delays import DelayReports

Outside callerconsumer surface

from meridian.shipping.commands import RegisterShipment

A surface exports selected symbols to a named audience. It does not make the boundary's descendants public.

For coding agents

Full reference.
Compact instructions.

Ownership, composition, and import rules for your Python coding agent. Start with a blank Python project and a prompt for your own business requirements.

Python + FastAPI
From reference to prompt

Start with the full reference

A detailed architecture guide and working reference applications.

Less code to hold in your head.

Start with one boundary. Keep the next change local.

Read the practical guide