Tech Stack (Minimal)¶

This page summarises the minimal technology choices required to illustrate the architecture, without prescribing any specific cloud, database, or workflow engine.

Pseudocode Style¶

class Command(BaseModel):
    action: str
    args: dict

class Executor:
    def run(self, command: Command) -> str:
        """Return raw output; orchestration handles retries/timeouts."""

Keep examples minimal: show interfaces and data shapes; omit concrete infra calls.

Extensibility Guidance¶

Add new Executors without modifying Services or Orchestrators; selection happens via configuration.
Introduce lightweight parsing strategies only when raw output is not already structured (e.g., JSON). Prefer direct Pydantic parsing where possible.
Extend orchestration by composing multi-step or multi-system workflows (e.g., submit → poll → fetch output → validate).
Keep Command and Response models backward‑compatible to ensure stable API contracts for consuming test repositories.

These extension points preserve the framework’s layered architecture: BDD steps call orchestrators, orchestrators coordinate services, services delegate execution to pluggable executors, and typed models keep the data contract stable across environments (local, remote, cloud, or secure).

Non-Goals¶

Tying the framework to a specific cloud provider, database, or workflow engine
Embedding security / credential logic (delegated to environment or secrets manager)
Implementing complex performance tuning or workload‑specific optimisations

Future (Optional) Enhancements¶

Optional versioned documentation once the blueprint evolves into multiple major revisions
Link checking workflow to prevent stale references
Example test fixture taxonomy page (if code examples are expanded)

Suggestions welcome; propose changes via pull request following documentation style template.

Tech Stack & Rationale¶

This page explains why the chosen tools, languages, and patterns fit the architecture of a generic, layered BDD automation framework.
It focuses on principles, not vendors — everything here applies to cloud, on‑prem, secure environments, big‑data workloads, serverless, and mixed architectures.

1. Why Python?¶

Python is exceptionally well‑suited for a layered, command‑driven orchestration framework because:

🟦 Dynamic & Expressive¶

Minimal boilerplate allows clean domain models, executors, and orchestrators.
Easy to wrap CLIs, APIs, cloud SDKs, remote execution, or shell tools.
Interoperates naturally with subprocess, SSH libraries, async task runners, or API clients.

🟦 Excellent for Testing¶

Python has the richest testing ecosystem available today.
pytest + fixtures + parametrisation = fast, readable tests.
Perfect for BDD because steps feel natural and expressive.

🟦 Great for Secure / Hybrid Environments¶

Works identically on laptops, locked‑down edge nodes, CI machines, or containers.
Easy to run inside virtualenvs, conda, Docker, serverless runtimes, or system Python.

2. Why pytest & pytest‑bdd?¶

pytest provides the backbone of test execution:

🟨 Key Strengths¶

Clean, composable fixtures that map perfectly onto layers (steps → orchestrators → services).
Parametrised test cases without duplication.
Built‑in support for plugins and extension points.
Fast feedback loop for local development.

pytest-bdd adds:

Human‑readable Gherkin steps.
Automatic mapping of Given/When/Then to Python functions.
Reusable step libraries across repositories.

This aligns directly with the architectural goal: test intent is isolated from execution logic.

3. Why Pydantic Models?¶

Typed models are central to this framework:

🟪 Benefits¶

Validate workflow inputs (WorkflowRequest).
Normalise executor output (via CLIResponse).
Provide structured, version‑controlled WorkflowResponse objects.
Enhance debuggability and logging.
Enable consistent schemas across environments.

4. Why Command + Executor + Response Works Everywhere¶

This architecture maps cleanly to diverse environments:

🌍 Cloud (AWS, Azure, GCP)¶

Executors can wrap:

Batch jobs
Serverless invocation
Kubernetes jobs / ECS tasks
Workflow APIs
Secure bastion/edge-node command execution

🏢 On‑Prem or Secure Environments¶

Executors can wrap:

SSH
Message queues
CLI tools installed on controlled hosts
Air‑gapped runtime environments

📊 Big‑Data / Distributed Workflows¶

Works naturally for:

Distributed compute (Spark, Flink, Dask)
Orchestrators (Airflow-style, Oozie-style, custom schedulers)
Streaming/batch ingestion workflows
Long‑running jobs requiring polling

🧪 Developer Productivity¶

Developers run the same steps locally using:

Local CLI wrappers
Simulated/Mock executors
Minimal stubs
Local subprocess execution

The same steps run in CI/CD or secure runtime without modification.

5. Extensibility Guidance¶

The framework is designed to scale without rewriting core logic:

Add New Executors¶

Use configuration to select:

local subprocess
remote SSH/SSM
container runner
API-based job runner

No step or orchestrator changes required.

Add New Parsing Strategies (Optional)¶

Only needed when:

CLI output is unstructured
Log lines need normalisation
Formats vary across environments

If output is JSON, bypass parsing entirely via Pydantic.

Compose Multi-Step Orchestrators¶

Build sequences like:

submit → poll → fetch → validate
fan-out workflows → aggregate results
branching or conditional flows

All without modifying services or steps.

6. Non-Goals¶

Tying the architecture to a specific provider (AWS, GCP, Hadoop, etc.)
Embedding credentials or secrets in code (handled by environment)
Optimising for a single workload type
Adding unnecessary complexity or vendor-specific coupling

7. Recommended Reading Order¶

README.md – high-level blueprint
architecture-overview.md – execution flow & runtime model
layers.md – responsibilities of each layer
patterns.md – behavioural patterns (polling, command chain, etc.)
extending.md – CI/CD, versioning, package distribution
faq.md – common clarifications