Clean Architecture for Bash

Overview

Framework-agnostic, structured Bash architecture optimized for change, testability, and clear boundaries. Inner layers never call outer layer functions directly. Domain stays pure (no I/O, no external commands).

Target: Bash >=4.3 | set -euo pipefail | Pure domain | Tool-agnostic core | No global mutable state in domain

When to Use

• •Starting a new bash script/project that needs long-term maintainability
• •Reviewing existing shell scripts for architecture violations (I/O mixed with logic)
• •Deciding where a new function belongs (domain vs application vs adapter)
• •Structuring data flow between CLI input, business logic, and system output
• •Setting up testing strategy with proper isolation
• •Refactoring monolithic "god scripts" into clean architecture

When NOT to use:

• •One-liner scripts or trivial wrappers (<30 lines)
• •Scripts that are purely I/O orchestration with no business logic (simple rsync wrappers, etc.)
• •Use SCRIPT mode for single-file scripts (see script-mode.md)

Layers & Dependency Rule

Inner layers never call outer layer functions directly. Dependencies point inward only.

SOLID Adapted to Bash

Data Flow

CLI args -> validate (adapter boundary) -> domain functions (pure) -> format output (adapter) -> stdout/file
  (raw)     (composition/adapter)           (no I/O, no side effects)   (adapter boundary)       (external)

Never: Use global variables for data flow between layers. Globals acceptable only for: constants (readonly), configuration set once in composition root, and trap cleanup state.

Core Patterns

Ports (Function-Name Contracts)

Bash has no interfaces. Ports are documented function signatures that adapters must implement. Pass the function name to use cases.

# --- PORT CONTRACT ---
# port: read_config
# args: $1 = config file path
# stdout: key=value lines (one per line)
# return: 0 on success, 1 on not found, 2 on parse error

# --- ADAPTER (implements port) ---
adapter__read_config_file() {
    local file="$1"
    [[ -f "$file" ]] || return 1
    grep -v '^#' "$file" | grep -v '^$'
}

# --- USE CASE (receives port function name) ---
uc__load_settings() {
    local read_config_fn="$1"
    local config_path="$2"

    local raw
    raw=$("$read_config_fn" "$config_path") || return 1

    # Call domain function (pure)
    domain__parse_settings "$raw"
}

# --- COMPOSITION ---
main() {
    uc__load_settings adapter__read_config_file "/etc/myapp.conf"
}

Dependency Inversion via Function References

# Use case depends on abstraction (function name parameter), not concretion
uc__process_data() {
    local fetch_fn="$1"      # port: fetch data
    local store_fn="$2"      # port: store result
    local input="$3"

    local raw_data
    raw_data=$("$fetch_fn" "$input") || return 1

    local result
    result=$(domain__transform "$raw_data")

    "$store_fn" "$result"
}

# Composition wires concrete adapters
main() {
    uc__process_data \
        adapter__fetch_from_api \
        adapter__store_to_file \
        "$1"
}

Nameref for Structured Data (Bash 4.3+)

# Domain function populates associative array via nameref
domain__parse_record() {
    local input="$1"
    declare -n _out="$2"  # nameref to caller's associative array

    local key="${input%%:*}"
    local val="${input#*:}"
    _out[name]="$key"
    _out[value]="$val"
    # No I/O, no external commands — pure parameter expansion
}

# Caller
declare -A record
domain__parse_record "host:example.com" record
echo "${record[name]}"  # "host" -- I/O happens in adapter/composition

Error Handling

# Domain (pure validation)
domain__validate_port() {
    local port="$1"
    [[ "$port" =~ ^[0-9]+$ ]] || { echo "error: port must be numeric" >&2; return 1; }
    (( port >= 1 && port <= 65535 )) || { echo "error: port out of range" >&2; return 1; }
    echo "$port"  # return validated value
}

# Adapter (catches external failure)
adapter__check_port_open() {
    local host="$1" port="$2"
    timeout 5 bash -c "echo >/dev/tcp/$host/$port" 2>/dev/null || return 1
}

Exit Codes

Naming Conventions

Double underscore separates namespace from function name. Prevents collision with system commands.

Folder Layout (Multi-File)

project/
  bin/
    my-tool             # Entry point (sources lib, calls main)
  lib/
    domain.sh           # Pure functions: validation, transformation, computation
    application.sh      # Use cases: orchestration via port function references
    ports.sh            # Port contract documentation (comments only)
    adapters/
      file.sh           # File I/O adapter functions
      api.sh            # HTTP/API adapter functions
      system.sh         # System command adapter functions
    compose.sh          # Wiring: bind adapters to ports, call use cases
  tests/
    test_domain.sh      # Unit tests for domain (no mocking needed)
    test_application.sh # Use case tests with stub adapters
    test_integration.sh # Real adapters, real I/O

For single-file scripts, use comment-based section markers. See script-mode.md.

Guardrails: domain.sh sources nothing and calls no external commands. application.sh sources domain.sh only. adapters/*.sh implement port contracts. compose.sh sources everything and wires.

Source guards (prevent double-sourcing in multi-file projects):

# At the top of each library file (e.g., domain.sh)
[[ -n "${_DOMAIN_SH_LOADED:-}" ]] && return 0
readonly _DOMAIN_SH_LOADED=1

Testing Strategy

Stub Adapters for Testing

# Stub adapter (replaces real I/O for testing)
stub__read_config() {
    echo "host=localhost"
    echo "port=8080"
}

# Test use case with stub
test_load_settings() {
    local result
    result=$(uc__load_settings stub__read_config "/fake/path")
    [[ "$result" == *"localhost"* ]] || { echo "FAIL: expected localhost"; return 1; }
    echo "PASS: test_load_settings"
}

Observability

• •Structured logging to stderr: log_info "msg" >&2 (never to stdout — that's for data)
• •Thread TRACE_ID via environment variable or global (set once in composition root)
• •Log at adapter boundaries only; domain stays silent
• •Use PS4='+ ${BASH_SOURCE}:${LINENO}: ' with set -x for debug tracing

Non-Negotiables Checklist

• • Dependencies point inward only (domain calls nothing external)
• • Domain pure: no I/O, no external commands, no echo to terminal (only stdout for return values)
• • Use cases receive port function names as parameters (DIP)
• • set -euo pipefail at script top
• • Structured exit codes (not random numbers)
• • Boundary validation (arguments checked at adapter/composition boundary)
• • No global mutable state in domain/application (use namerefs or stdout)
• • Logging to stderr only; stdout reserved for data
• • Cleanup via trap in composition root (not scattered)
• • Functions prefixed by layer (domain__, uc__, adapter__)
• • shellcheck passes with no warnings (run: shellcheck -x script.sh)

Operating Modes

Refactoring Path (monolithic script -> clean arch)

1. •Identify pure logic (validation, computation, string processing) -> move to domain__ functions
2. •Identify I/O operations (file reads, API calls, system commands) -> wrap in adapter__ functions
3. •Identify orchestration sequences -> extract to uc__ use case functions
4. •Document port contracts for each adapter function signature
5. •Make use cases receive adapter function names as parameters
6. •Create main() as composition root: parse args, wire adapters, call use cases
7. •Add set -euo pipefail and structured exit codes
8. •Write domain unit tests (pure function tests, no mocking)
9. •Write stub adapter tests for use cases

Common Mistakes

Reference Files

Glossary