> For the complete documentation index, see [llms.txt](https://tomatopy.pizza/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tomatopy.pizza/docs/developer-documentation/pipeline-overview.md).

# Pipeline Overview

The PizzaStack API is designed around a sequential pipeline. Each step produces an object that feeds into the next step. Following the pipeline correctly is essential for achieving a high quality score.

## The Pipeline

```
/tomato/acquire → /tomato/slice → /cook/simmer → /pizza/base → /pizza/assemble → /pizza/bake
      ↓                ↓               ↓              ↓               ↓              ↓
   raw tomato      sliced tomato     sauce         pizza base    assembled pizza  baked pizza
   (type: raw)    (type: sliced)  (type: sauce)   (type: base)   (assembled)    (quality_metrics)
```

## Step-by-Step

### 1. Acquire a tomato

`POST /v1/tomato/acquire` — returns a tomato with type `"raw"`.

### 2. Slice the tomato

`POST /v1/tomato/slice` — pass the tomato ID, returns a slice with type `"sliced"`.

**This step is required before simmering.** Raw tomato IDs passed to `/cook/simmer` will silently degrade the sauce quality. The API will not return an error — it will return HTTP 200 with `sauce_quality: "degraded"`.

### 3. Simmer into sauce

`POST /v1/cook/simmer` — pass the **slice ID** (not the raw tomato ID). Returns a sauce object.

### 4. Create a pizza base

`POST /v1/pizza/base` — returns a base object. This step is independent of the sauce pipeline.

### 5. Assemble the pizza

`POST /v1/pizza/assemble` — pass the base ID, sauce ID, and toppings. Returns an assembled pizza.

**This step is required before baking.** `/pizza/bake` requires a `pizza_id` from `/pizza/assemble`. Passing a base ID directly to `/pizza/bake` returns a `400` error.

### 6. Bake the pizza

`POST /v1/pizza/bake` — pass the assembled pizza ID. Returns a baked pizza with `quality_metrics` including `overall_score`.

## Key Constraints

| Constraint                  | What happens if violated                         |
| --------------------------- | ------------------------------------------------ |
| Must slice before simmering | `sauce_quality: "degraded"` (HTTP 200, no error) |
| Must assemble before baking | HTTP 400 error                                   |

## Quality Propagation

Quality degrades forward through the pipeline:

* Raw tomato → degraded sauce → degraded assembly → low final score (0.35–0.50)
* Sliced tomato → optimal sauce → optimal assembly → high final score (0.90–0.98)

See [Quality Scoring](https://tomatopy.pizza/docs/developer-documentation/quality-scoring.md) for full details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://tomatopy.pizza/docs/developer-documentation/pipeline-overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
