> For the complete documentation index, see [llms.txt](https://robodex.gitbook.io/robodex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://robodex.gitbook.io/robodex-docs/architecture/data-flow.md).

# End To End Data Flow

## Prompt to body

```mermaid
sequenceDiagram
    participant User
    participant Web as Workspace UI
    participant WS as Workspace route
    participant SDK as RobotWorkspaceSDK
    participant Designs as /designs/generate
    participant Registry as Agent loop registry
    participant Loop as Agent loop
    participant Program as Robot program compiler
    participant Store as WorkspaceStore

    User->>Web: Describe a robot task
    Web->>WS: POST /workspace/threads/{id}/generate
    WS->>SDK: generate_for_thread()
    SDK->>Designs: generate_designs()
    Designs->>Registry: run_agent_loop()
    Registry->>Loop: grammar_v2 or creative_qd_v2
    Loop->>Program: compile_robot_design_program()
    Program-->>Loop: graph, component program, HITL
    Loop-->>Registry: AgentLoopResult
    Registry-->>Designs: state + hitl
    Designs->>Store: save designs, revisions, checkpoints
    Store-->>SDK: persisted candidates
    SDK-->>Web: assistant message + robot artifact
```

## Generated data shapes

| Shape                | Owner                      | Description                                                               |
| -------------------- | -------------------------- | ------------------------------------------------------------------------- |
| Prompt               | Frontend and workspace SDK | Natural-language task request from the user                               |
| `AgentLoopConfig`    | Research protocol          | Population, attempts, confirmation, agents, and extra options             |
| `RobotDesignProgram` | Pipeline                   | Derivation-first grammar program                                          |
| `ExpandedRobotGraph` | Pipeline                   | Expanded graph of nodes, edges, symbols, and metadata                     |
| `ComponentProgram`   | Pipeline                   | Lowered component-level body description                                  |
| `RobotDesignHitlV2`  | Pipeline                   | Reviewable payload with summary, validity, graph, components, and program |
| Product candidate    | API route                  | Flat frontend-facing candidate bundle                                     |
| Thread artifact      | Workspace SDK              | Saved artifact attached to a chat thread                                  |
| Concept geometry     | Frontend viewer            | Three.js primitives derived from flat candidate fields                    |

## Ingest to generation

The ingest route can enrich a task before generation:

1. `POST /ingest` records the raw prompt.
2. `DemoService.analyze_prompt()` asks the configured model to produce a plan and search queries.
3. The route may select a YouTube reference, skip search via `SKIP_YOUTUBE_SEARCH=1`, or fall back to a DROID-style reference.
4. The ingest job is persisted in `workspace_store`.
5. `POST /designs/generate` loads the ingest job and uses `plan.task_goal` or `selected_query` as the generation prompt.

Workspace generation can also create a synthetic ingest job directly from a chat prompt. That keeps the design route reusable without requiring the user to pass through a video-ingest flow.

## Body to render

The current frontend viewer does not require a complete MJCF file to show a candidate. It can build a concept model from flat fields such as:

* embodiment,
* torso dimensions,
* leg count,
* arm count,
* limb degrees of freedom,
* actuator class,
* sensor list,
* compile-safe flag.

`MorphologyViewer.tsx` uses those fields to construct Three.js primitives for a quick visual inspection. Engineering exports remain separate.

## Body to export

Export endpoints use stored design data:

1. A design is converted to `RobotDesignIR` by `_design_to_ir()`.
2. `compile_to_mjcf()` emits MJCF XML.
3. engineering render helpers can produce UI scene data.
4. CAD and print export helpers can produce print-oriented files.
5. artifacts are saved back to `workspace_store`.

Some generated candidates are still concept-first. A compile-safe grammar program does not automatically mean the product has a final printable mechanical design.


---

# 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 dynamically by asking a question.

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

```
GET https://robodex.gitbook.io/robodex-docs/architecture/data-flow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.