Question 1

How do I structure a Bash script with clean architecture?

Accepted Answer

Split functions into four layers: pure domain functions with no I/O, use case functions that orchestrate via port references, adapter functions that perform I/O, and a main composition root that wires adapters to use cases. Prefix functions with domain__, uc__, and adapter__.

Question 2

How do I test Bash scripts without a mocking framework?

Accepted Answer

Domain functions are pure and testable by direct calls. For use cases, write stub adapter functions matching the port contract signatures and pass their names as arguments, replacing real I/O with fixed test data.

Question 3

What Bash version is required for clean architecture patterns?

Accepted Answer

Bash 4.3 or later is required because structured data passing relies on namerefs (declare -n). Systems stuck on Bash 3.2, such as default macOS, must avoid namerefs and pass data via stdout instead.

Question 4

When should I not use clean architecture for a shell script?

Accepted Answer

Skip it for one-liners, trivial wrappers under about 30 lines, and scripts that are pure I/O orchestration with no business logic, such as a simple rsync wrapper. The layering overhead only pays off when logic must be tested and maintained.

Question 5

Why must Bash domain functions avoid external commands like grep or curl?

Accepted Answer

External commands are I/O and belong in adapters. Keeping the domain pure makes it deterministic and unit-testable without mocking, and prevents hidden side effects such as command injection from unvalidated input reaching a shell.

coding-bash-clean-architecture

SYSTEM DOCUMENTATION & REQUIREMENTS

Frequently Asked Questions about coding-bash-clean-architecture

Related Skills

shellcheck-configuration

cron-scheduling

shell-script-quality

bun