# Workflow

A workflow groups configurations for services to perform distinct use cases. By default, Stoobly provides configurations for the record, mock and test workflows.

## Background

To learn more about the role of individual services, see:

{% content-ref url="/pages/CV2FP4ZBSIpH9GCwJxyX" %}
[Service](/core-concepts/scaffold/service.md)
{% endcontent-ref %}

To run a workflow, see:

{% content-ref url="/pages/7J10qWFxe9zweKA3YQtH" %}
[How to Run a Workflow](/guides/how-to-integrate-e2e-testing/how-to-run-a-workflow.md)
{% endcontent-ref %}

To validate a workflow, see:

{% content-ref url="/pages/mrxE2H3fxfCSRj8hF0QQ" %}
[Validation](/core-concepts/scaffold/validation.md)
{% endcontent-ref %}

## File Structure

{% hint style="info" %}
To learn how each file is used, see [here](/core-concepts/scaffold/service.md#containers).
{% endhint %}

{% hint style="warning" %}
Any hidden file will be overritten when the scaffold service create command is rerun.
{% endhint %}

<details>

<summary>bin/init</summary>

First script that executes when a workflow runs. Should contain any commands needed for the service to initialize. Can also contain configuration commands for Stoobly. See [filter rules](/core-concepts/agent/proxy-settings/filter-rules.md), [match rules](/core-concepts/agent/proxy-settings/match-rules.md), and [rewrite rules](/core-concepts/agent/proxy-settings/rewrite-rules.md).

</details>

<details>

<summary>bin/.init</summary>

Maintained file that will be overriden on scaffold create.

</details>

<details>

<summary>docker-compose.yml</summary>

Custom docker-compose.yml file. Container services defined in this should should include:

* Respective `<WORKFLOW-NAME>` under the `profiles` property
* Either `app.egress` or `app.ingress` under the `networks` property

</details>

<details>

<summary>.docker-compose.&#x3C;WORKFLOW-NAME>.yml</summary>

Maintained file that will be overriden on scaffold create.

</details>

<details>

<summary>fixtures.yml</summary>

Enables defining mock responses for specific URL patterns. To learn more see [here](/core-concepts/mock-api/fixtures.md).

</details>

<details>

<summary>lifecycle_hooks.py</summary>

Enables reading and modifying requests during specific points in their lifecycle. To learn more see [here](/core-concepts/agent/lifecycle-hooks.md).

</details>

<details>

<summary>public</summary>

Enables defining mock request paths and responses using files stored in this folder. To learn more see [here](/core-concepts/mock-api/public-folder.md).

</details>

## Core Workflows

### Record

<figure><img src="/files/WGwtUwZxrplo52GmnOpW" alt=""><figcaption><p>Flow diagram for recording requests</p></figcaption></figure>

The journey of a request:

1. A request gets sent from the host e.g. browser or cURL
2. Gets sent to the gateway service
3. Gateway service routes the request based on hostname
4. Request gets intercepted by Stoobly running as a proxy
   1. Lifecycle hooks get triggered
5. Stoobly reverse proxies the request to the local or external API
6. On response, Stoobly records the request to its respective `.stoobly`folder
   1. Lifecycle hooks get triggered

### Mock

<figure><img src="/files/ftPAP5QoKPl0uLI3ijNd" alt=""><figcaption><p>Flow diagram for mocking requests</p></figcaption></figure>

The journey of a request:

1. A request gets sent from the host e.g. browser or cURL
2. Gets sent to the gateway service
3. Gateway service routes the request based on hostname
4. Request gets intercepted by Stoobly running as a proxy
   1. Lifecycle hooks get triggered
5. Stoobly mocks requests if it has been previously recorded. If the request is not found, it can conditionally reverse proxy the request to the local or external API
   1. Lifecycle hooks get triggered

### Test

<figure><img src="/files/6oPIduIpIncGYnAaaLSr" alt=""><figcaption><p>Flow diagram for testing an application that sends requests</p></figcaption></figure>

The journey of a request:

1. A request gets sent from the entrypoint service
2. Gateway service routes the request based on hostname
3. Request gets intercepted by Stoobly running as a proxy
   1. Lifecycle hooks get triggered
4. Stoobly mocks requests if it has been previously recorded. If the request is not found, it can conditionally reverse proxy the request to the local or external API
   1. Lifecycle hooks get triggered


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stoobly.com/core-concepts/scaffold/workflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.