Skip to content

Source Layout and Ownership

Atlas source layout is meant to teach the architecture without requiring tribal knowledge.

Canonical Ownership Model

flowchart LR
    Adapters[src/adapters] --> Inbound[CLI and HTTP]
    Adapters --> Outbound[Store sqlite redis fs telemetry]
    App[src/app] --> UseCases[Use cases and ports]
    Contracts[src/contracts] --> Stable[Stable schemas and errors]
    Domain[src/domain] --> Rules[Business rules]
    Runtime[src/runtime] --> Wiring[Runtime config and composition]

This ownership map gives contributors a direct translation from architectural idea to source-tree location. It exists so new code placement does not depend on local folklore or past directory names.

Why These Roots Exist

flowchart TD
    Domain[Pure rules] --> App[Orchestration]
    App --> Adapters[Integrations]
    Contracts --> Domain
    Contracts --> Adapters
    Runtime --> App
    Runtime --> Adapters

This diagram explains the dependency intent behind the root layout. The point is not just tidy directories; it is making responsibility and change impact easier to reason about.

The canonical roots are:

  • adapters
  • app
  • contracts
  • domain
  • runtime

These are the roots contributors should optimize for when placing new code.

Ownership Rules

  • if the code translates between Atlas and the outside world, it belongs in adapters
  • if the code orchestrates use cases and ports, it belongs in app
  • if the code defines stable schemas, config contracts, or errors, it belongs in contracts
  • if the code defines business rules and domain semantics, it belongs in domain
  • if the code wires the process together, it belongs in runtime

Architectural Benefit

This layout makes it harder to hide source of truth behind historical barrels or convenience shims.

Quick Placement Test

  • if you are translating HTTP, CLI, filesystem, or network concerns, start in adapters
  • if you are composing use cases or ports, start in app
  • if you are defining stable promises, start in contracts
  • if you are defining rules that should not depend on transport, start in domain
  • if you are wiring concrete runtime behavior, start in runtime

Purpose

This page explains the Atlas material for source layout and ownership 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.