Architecture Overview¶

This page provides a high‑level view of how the generic BDD automation framework fits into a modern, cloud‑centric delivery pipeline.
The focus is on separation of concerns, environment‑agnostic execution, and secure workflow testing across both local and remote environments.

System Context (Conceptual)¶

The framework is intentionally designed to operate inside secure, cloud‑based environments—such as major public cloud platforms—while still enabling rapid developer iteration, repeatable CI execution, and consistent validation across all stages of delivery.

_{Vector version: Download SVG}

High‑Level Flow (Developer → CI → Secure Runtime)¶

The diagram below illustrates how test intent flows cleanly from developer to CI to a secured runtime without leaking infrastructure concerns into steps or services.

flowchart LR
  Dev[Developer Laptop<br/>Local/Remote Execution] --> Repo[Source Control]
  Repo --> CI[CI Pipeline<br/>Tests + Reporting]
  CI --> FW[BDD Framework Layer<br/>Steps • Orchestrators • Services]
  FW --> Exec[Executor<br/>Local or Remote]
  Exec --> Cloud[Secure Runtime<br/>Auth • Networking • Policy]
  Cloud --> Engine[Workflow Engine<br/>Serverless • Batch • Big Data]

Core Architectural Ideas¶

🔹 1. Environment‑Agnostic Execution¶

Tests run identically whether executed:

• Locally on a developer laptop
• Through CI
• On a secure edge node
• Inside a restricted cloud environment

The Executor abstraction is the boundary that isolates execution mechanics. Whether a command runs via subprocess, an edge node, a container, or a cloud API, the test logic and BDD steps remain unchanged.

🔹 2. Orchestrators Own Workflow Lifecycles¶

Orchestrators handle:

• Submitting workflows
• Polling until completion
• Returning structured results

They express intent, not execution detail.
This keeps long‑running or asynchronous workflows predictable, testable, and fully decoupled from low‑level runtime differences.

🔹 3. Services Build & Interpret Commands¶

Services:

• Construct command objects (Command)
• Choose how to execute them (via the configured executor)
• Parse responses into structured models

Parsing may be achieved through a minimal parser or by binding directly to typed models when responses are already structured (e.g., JSON). The parsing layer is intentionally lightweight and optional.

🔹 4. Typed Models Provide Safety and Clarity¶

Pydantic (or equivalent) models represent:

• Workflow requests
• Status objects
• Final results
• Clear versioning boundaries between test artefacts and execution artefacts

This ensures:

• Strong validation
• Consistent results across environments
• Clear structure for orchestrators and steps

🔹 5. Decoupling Test Code from Infrastructure¶

The architecture avoids:

• Hardcoding hostnames
• Embedding CLI strings in steps
• Mixing execution logic with assertion logic

This allows:

• Easier refactoring
• Multi‑environment portability
• Readable, stable BDD steps that remain unchanged even as infrastructure evolves

Why This Architecture Works Well in Secure / Cloud Environments¶

• Ideal for locked‑down cloud accounts, private networking models, and constrained execution environments where direct access is limited.
• Works with edge nodes, containers, serverless workflows, or big‑data engines.
• Fully compatible with: -- Enterprise authentication and authorization (for example, identity tickets and role‑based access controls) -- Batching and other long‑running jobs -- Streaming and event‑driven workloads -- Workflow schedulers and orchestration engines

The core idea:
Tests describe intent.
The framework handles everything else.

This separation of concerns ensures that high‑security requirements never prevent teams from delivering reliable, automated workflow testing.

Next Steps¶

• Explore the detailed Layers documentation for each module.
• Review Patterns to understand orchestration, polling, and extensibility.
• See Decoupling & Distribution for versioning and packaging considerations.