Coding Bash Clean Architecture

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)

Capability check (REVIEW / judgment). Judging architecture/layer violations (I/O mixed with logic, wrong function placement) is capability-sensitive - a weaker model misjudges it. Run REVIEW mode on a pinned sonnet subagent (opus for a large or high-stakes codebase); pin the tier per dispatch, never inherit the session model. If you keep it inline and the session is on a lesser tier, offer switch-model-or-continue. See bitranox:process-agents-subagent-driven-development ("The session model is fixed" / "Concrete tiers").

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
}

domain__validate_host() {
    local host="$1"
    # A host reaches a shell redirection in the adapter below, so "is this a hostname" is a
    # domain rule with a security consequence: anything outside this set is not a hostname.
    [[ "$host" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$ ]] \
        || { echo "error: host is not a valid hostname" >&2; return 1; }
    echo "$host"
}

# Adapter (catches external failure)
adapter__check_port_open() {
    local host="$1" port="$2"
    # The script body is SINGLE-quoted and the values arrive as positional arguments. Interpolate
    # them into a double-quoted body instead and `bash -c` re-parses them AS CODE: a host of
    # `a;id;x` read from a config file then runs `id`. Validating in the domain is the first
    # defence, this is the one that holds when validation is bypassed or wrong.
    timeout 5 bash -c 'exec 3<>"/dev/tcp/$1/$2"' _ "$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; the domain emits no LOG lines. This is about logging, not error reporting: a domain function may still write one error: ... line to stderr before return 1 (see Error Handling), which is its error channel, not a log.
• Use PS4='+ ${BASH_SOURCE}:${LINENO}: ' with set -x for debug tracing

Non-Negotiables Checklist

• Dependencies point inward only (domain calls nothing external)
• Domain pure: stdout only for return values, stderr only for an error: ... line before return 1; no other I/O, no external commands, no env mutation
• 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
10. Register trap cleanup once in the composition root
11. Run shellcheck -x script.sh and fix every warning - this is the only runnable gate in the skill, so the path is not finished until it passes clean

Red Flags

The "When NOT to use" exemptions above are real, but they are also the easiest thing to talk yourself into. These thoughts mean STOP - you are rationalizing:

Common Mistakes

Reference Files

Use the Read tool to load the reference file for the mode you are in (GENERATE -> canonical-example.md, REVIEW -> review-checklists.md, SCRIPT -> script-mode.md); do not answer from the tables above alone.

Glossary