# https://github.com/rocketride-org/rocketride-server Project Manual Generated at: 2026-06-23 19:26:26 UTC ## Table of Contents - [Repository Overview & System Architecture](#page-1) - [Pipeline System, Nodes & Execution Model](#page-2) - [SDKs, Clients & IDE Integration](#page-3) - [Deployment, Observability & Operations](#page-4) ## Repository Overview & System Architecture ### Related Pages Related topics: [Pipeline System, Nodes & Execution Model](#page-2), [SDKs, Clients & IDE Integration](#page-3), [Deployment, Observability & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md) - [pnpm-workspace.yaml](https://github.com/rocketride-org/rocketride-server/blob/main/pnpm-workspace.yaml) - [pyproject.toml](https://github.com/rocketride-org/rocketride-server/blob/main/pyproject.toml) - [apps/engine/CMakeLists.txt](https://github.com/rocketride-org/rocketride-server/blob/main/apps/engine/CMakeLists.txt) - [packages/server/CMakeLists.txt](https://github.com/rocketride-org/rocketride-server/blob/main/packages/server/CMakeLists.txt) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/llamaparse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llamaparse/README.md) - [nodes/src/nodes/reducto/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/reducto/README.md) - [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md) - [nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md) - [nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_code/README.md) - [nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/summarization/README.md) - [nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md) - [nodes/src/nodes/tool_github/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_github/README.md) - [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - [nodes/src/nodes/atlas/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/atlas/README.md) - [nodes/src/nodes/llm_deepseek/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_deepseek/README.md) - [nodes/src/nodes/llm_perplexity/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_perplexity/README.md) - [nodes/src/nodes/llm_baidu_qianfan/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_baidu_qianfan/README.md) - [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)
# Repository Overview & System Architecture ## 1. Purpose and Scope RocketRide Server is a polyglot pipeline engine for building and running document-, image-, and LLM-driven AI workflows. The system is structured as a **monorepo** that ships three coordinated deliverables: a high-performance C++ execution engine, a library of Python-based processing nodes, and a TypeScript/React VS Code shell that authors and launches pipelines. Pipeline definitions (e.g. `examples/vision.pipe`) are evaluated end-to-end by the engine, with data moving between nodes through typed input/output "lanes" such as `data`, `text`, `documents`, `table`, `image`, and `answers`. Source: [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) The repository is organized as a pnpm workspace with a parallel Python package tree. Source: [pnpm-workspace.yaml](https://github.com/rocketride-org/rocketride-server/blob/main/pnpm-workspace.yaml) and [pyproject.toml](https://github.com/rocketride-org/rocketride-server/blob/main/pyproject.toml). The C++ engine is built with CMake for both the standalone `engine` and the embedded `server` packaging. Source: [apps/engine/CMakeLists.txt](https://github.com/rocketride-org/rocketride-server/blob/main/apps/engine/CMakeLists.txt) and [packages/server/CMakeLists.txt](https://github.com/rocketride-org/rocketride-server/blob/main/packages/server/CMakeLists.txt). ## 2. System Architecture ```mermaid flowchart TB User[VS Code User] --> ShellUI[Shell UI
apps/shell-ui
TypeScript + React] ShellUI -->|author/launch .pipe| Engine[C++ Engine
apps/engine] Engine -->|subprocess IPC| Nodes[Python Node Library
nodes/src/nodes] Nodes -->|HTTPS / SDKs| Cloud[Cloud Services
LlamaParse, Reducto,
Landing.ai, LLMs] Nodes -->|pymongo / chromadb| Stores[Vector Stores
Atlas, Chroma] Engine -->|FLOW trace events| ShellUI ``` The shell UI is a workspace-persistent editor model. Documents are keyed by URI, tracked for dirty/version state, and grouped into editor splits through a recursive `LayoutNode` tree. Source: [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx). The C++ engine spawns Python node processes, exchanges serialized messages, and emits `>DBG` FLOW-trace events back to the parent shell. The `dropper` component at the pipeline entry point is a common pain point — community issue #1335 reports that the "Browse files" button does not respond to clicks, indicating event-handling regressions in this UI surface. ## 3. Node System and Pipeline Model Every node in `nodes/src/nodes` declares typed **lanes** that describe how it consumes and emits data. The core `parser` node, for instance, accepts a single `data` lane and routes its outputs to `text`, `table`, `image`, `audio`, and `video` lanes. Source: [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md). This lane-based contract is what makes pipelines composable — a node's `Lane out` is the next node's `Lane in`. Nodes also declare a `classType` (e.g. `["store", "tool"]`) and capabilities such as `invoke`, which determines how an agent can call them. The Chroma node exposes `chroma.search`, `chroma.upsert`, and `chroma.delete` to any agent in the same pipeline, all namespaced by `serverName`. Source: [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md). The GitHub tool node goes further, exposing the full REST surface (issues, PRs, reviews, releases, workflows, search, commits) and supports a `readOnly` mode to disable mutating calls. Source: [nodes/src/nodes/tool_github/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_github/README.md). Several node families exist: - **Parsers**: built-in `core/parser` plus third-party integrations for LlamaParse (simple/advanced modes, timeouts that scale with file size), Reducto (Markdown + table blocks, AI diagram summarization), and Landing.ai ADE (parse + extract). Source: [nodes/src/nodes/llamaparse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llamaparse/README.md), [nodes/src/nodes/reducto/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/reducto/README.md), [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md). - **Preprocessors**: LangChain text splitter (`RecursiveCharacterTextSplitter` with configurable `strlen`/`tokens` modes) and a tree-sitter code splitter that respects syntactic boundaries per language. Source: [nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md), [nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_code/README.md). - **LLMs**: profile-driven connectors for Deepseek, Perplexity (`sonar-pro`), and Baidu Qianfan (`ernie-4.5-turbo-128k` and others). Each carries its own context/output token budget. Source: [nodes/src/nodes/llm_deepseek/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_deepseek/README.md), [nodes/src/nodes/llm_perplexity/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_perplexity/README.md), [nodes/src/nodes/llm_baidu_qianfan/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_baidu_qianfan/README.md). - **Agents & Summarization**: a LangChain agent that supports nested sub-agents and instructions, and a summarization node that emits summaries, key points, and entities with chunked LLM calls. Source: [nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md), [nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/summarization/README.md). - **Vector Stores**: Atlas (requires M10+ or serverless) and Chroma (local or cloud). Both require pre-embedded documents; chunks without embeddings are rejected. Source: [nodes/src/nodes/atlas/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/atlas/README.md). ## 4. Observability and Known Failure Modes The engine supports trace levels for debugging. At `pipelineTraceLevel: 'full'`, each node's `model_dump()` payload — including raw image bytes — is inlined into `>DBG` FLOW events on the subprocess→parent stdout channel. Community issue #1337 documents that a single 30 MP image can produce a line exceeding 16 MB, which the parent process cannot ingest, so `full` traces are unsafe for vision pipelines until payload size is bounded. Community issue #1338 reports a related performance pathology: a 30 MP image spends ~28–38 s in redundant full-resolution PNG decode/encode round-trips along the shared `image` path used by `examples/vision.pipe` (`dropper → parse → detect → response_image`). Model inference itself is ~0.5 s, so the wall-clock time is dominated by serializing image bytes through intermediate stages. When designing pipelines that handle large binary payloads, prefer lanes that pass references rather than re-encoding, and avoid `full` trace levels on production vision runs. ## See Also - [Pipeline Authoring Guide](https://github.com/rocketride-org/rocketride-server/wiki) (planned) - [Node SDK Reference](https://github.com/rocketride-org/rocketride-server/wiki) (planned) - [Shell UI Architecture](https://github.com/rocketride-org/rocketride-server/wiki) (planned) --- ## Pipeline System, Nodes & Execution Model ### Related Pages Related topics: [Repository Overview & System Architecture](#page-1), [Deployment, Observability & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [nodes/src/nodes/autopipe/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/autopipe/README.md) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/summarization/README.md) - [nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md) - [nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_code/README.md) - [nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md) - [nodes/src/nodes/atlas/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/atlas/README.md) - [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - [nodes/src/nodes/db_mysql/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/db_mysql/README.md) - [nodes/src/nodes/tool_firecrawl/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_firecrawl/README.md) - [nodes/src/nodes/llamaparse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llamaparse/README.md) - [nodes/src/nodes/reducto/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/reducto/README.md) - [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)
# Pipeline System, Nodes & Execution Model RocketRide models data processing as a directed graph of **nodes** connected by typed **lanes**. A `.pipe` file describes this graph declaratively; the C++ engine instantiates it at build time, inserting helpers such as the `autopipe` meta-node, and runs the resulting flow through Python sub-pipelines. ## What a Pipeline Is A pipeline is the unit of work. Each node declares a set of input lanes (e.g. `data`, `text`, `questions`, `documents`) and output lanes (e.g. `text`, `table`, `image`, `answers`, `documents`). Lanes are typed by payload shape — raw bytes, text, tabular rows, structured documents — and the engine only routes a lane if a downstream listener is wired to consume it. For example, the core Parser exposes five output lanes from a single `data` input and emits nothing on lanes that have no subscriber ([nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md)). Output is filtered the same way in cloud-parsing nodes such as `reducto`, which explicitly buffers the byte stream and only produces output for lanes with downstream listeners ([nodes/src/nodes/reducto/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/reducto/README.md)). ```mermaid flowchart LR Dropper[Dropper\ndata in] --> Parse[Parser\ndata → text/table/image/audio/video] Parse --> Detect[Detect\nimage → answers] Parse --> Summarize[Summarization\ntext → text/documents] Summarize --> Embed[Embedding\ndocuments → documents] Embed --> Store[(Vector Store\natlas / chroma)] Dropper -.parse.-> OCR[OCR filter] Detect --> Response[response_image\nimage → image] ``` ## Node Catalogue Nodes are grouped by role: | Role | Examples | Purpose | |---|---|---| | Ingest / I/O | `dropper`, `response_image` | Move data in and out of the pipeline; the Dropper source powers the file-picker UI (issue [#1335](https://github.com/rocketride-org/rocketride-server/issues/1335)). | | Parse / OCR | `parser` (core), `llamaparse`, `reducto`, `landing_ai/parse` | Extract text, tables, images, audio, and video from raw documents. | | Preprocess | `preprocessor_langchain`, `preprocessor_code` | Split text or source code into chunked documents for downstream embedding. | | LLM / Agent | `llm_*` providers (Bedrock, DeepSeek, Perplexity, Baidu Qianfan), `agent_langchain` | Generate completions or drive tool-using agents. | | Tool | `tool_firecrawl`, `db_mysql` | Expose callable tools (scrape, query DB) to agents. | | Summarization | `summarization` | Produce summary, key points, and entities from accumulated text. | | Vector Store | `atlas`, `chroma` | Persist pre-embedded chunks and retrieve by semantic or keyword search. | | Meta | `autopipe` | Not added by users — assembles the parse/process/embed stack automatically. | Each node ships a small manifest: lanes, fields, optional **profiles**, and a list of dependencies. The schema block is generated and marked `ROCKETRIDE:GENERATED:PARAMS`, so it stays in sync with the UI shape (see the `Schema` section of any node README, e.g. [nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/summarization/README.md)). ## Profiles and Configuration Profiles are user-selectable presets that swap a node's exposed fields and behaviour without rewriting the graph. The `summarization` node, for instance, ships a single `default` profile controlling the number of summaries, key points, and entities ([nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/summarization/README.md)). `chroma` exposes `local` and `cloud` profiles that change the connection path and authentication scheme ([nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md)), while `preprocessor_langchain` supports `strlen` and `character` chunking modes and accepts comma-separated Python string literals for separators ([nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md)). `preprocessor_code` similarly uses content-based heuristics when `language: auto` is selected, falling back to a per-file skip and warning if no grammar matches ([nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_code/README.md)). ## Execution Model and the `autopipe` Meta-Node The engine runs in one of five operation modes — `CONFIG`, `SOURCE_INDEX`, `INDEX`, `INSTANCE`, or `TRANSFORM` — and `autopipe` inspects the current mode plus the task's sub-configurations during `beginGlobal` to splice in the correct filter stack ([nodes/src/nodes/autopipe/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/autopipe/README.md)): | Mode | Filters inserted | |---|---| | `INDEX` | vector store (if `store` set) → indexer | | `INSTANCE` | parse → (OCR) → (indexer) → preprocessor → embedding → store | | `TRANSFORM` | parse → (OCR) → preprocessor → embedding → store | | `CONFIG`, `SOURCE_INDEX` | nothing | The inserted instances receive fixed ids (`parse_1`, `ocr_1`, `indexer_1`, `preprocessor_1`, `embedding_1`, `vector_1`). `autopipe` is registered as a `filter` of class `other` and capability `internal`; it defines no lanes of its own, and the OCR/indexer toggles are read from the engine's `include*` flags rather than from autopipe's own config. Users therefore rarely add `autopipe` manually — it is wired by the pipeline engine. ## Lanes, Documents, and the Workspace Documents flow through the pipeline as typed records carrying a `chunkId` (per object) and optional table metadata (`isTable`, `tableId`). The vector store nodes consume these documents on `documents` and emit them on `documents` / `answers` / `questions` depending on the operation; `atlas` requires an M10+ or serverless cluster and pre-creates regular, text, and `knnVector` indexes on first ingest ([nodes/src/nodes/atlas/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/atlas/README.md)). Agent nodes (`agent_langchain`) accept an `instructions` array, an `agent_description`, and a profile, and wire into other nodes through the `llm` and tool channels ([nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md)). On the UI side, open documents are stored in a workspace-backed `appState` under the `documents` key with a 500 ms debounced persist ([apps/shell-ui/src/lib/Documents.tsx:41-49](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)). ## Common Failure Modes Community-reported issues cluster around the I/O and tracing surfaces of this model: - **Vision throughput.** A 30 MP image spends ~28–38 s in redundant full-resolution PNG decode/encode round-trips along the dropper → parse → detect → response_image path; model inference is only ~0.5 s of that ([#1338](https://github.com/rocketride-org/rocketride-server/issues/1338)). - **Full tracing inlines bytes.** Setting `pipelineTraceLevel: 'full'` causes the C++ engine to dump every node's `model_dump()` payload — including raw image bytes — into a single `>DBG` FLOW event that can exceed the 16 MB subprocess stdout limit ([#1337](https://github.com/rocketride-org/rocketride-server/issues/1337)). - **Dropper "Browse files" button.** Clicking the inner label does not open the file picker, while clicking the outer square does ([#1335](https://github.com/rocketride-org/rocketride-server/issues/1335)). ## See Also - Parser node — [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - Autopipe meta-node — [nodes/src/nodes/autopipe/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/autopipe/README.md) - Vector stores — [nodes/src/nodes/atlas/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/atlas/README.md), [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - Workspace UI — [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx) --- ## SDKs, Clients & IDE Integration ### Related Pages Related topics: [Repository Overview & System Architecture](#page-1), [Deployment, Observability & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md) - [packages/client-python/src/rocketride/client.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-python/src/rocketride/client.py) - [packages/client-typescript/src/client/client.ts](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-typescript/src/client/client.ts) - [packages/client-mcp/src/rocketride_mcp/server.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-mcp/src/rocketride_mcp/server.py) - [apps/vscode/src/extension.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/extension.ts) - [apps/vscode/src/engine/engine-manager.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/engine/engine-manager.ts) - [apps/vscode/src/engine/engine-registry.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/engine/engine-registry.ts) - [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - [nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md)
# SDKs, Clients & IDE Integration ## Overview RocketRide ships a multi-language client surface that lets users compose, debug, and run AI pipelines from inside an IDE, from the terminal, or from another AI agent. The repository is organized as three coordinated layers: - A high-throughput **C++ engine** that executes pipelines (`README.md`). - A catalog of **nodes** — Python packages such as Parser, Chroma, Landing.ai, LlamaParse, and LangChain agents — that the engine orchestrates ([nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md), [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md)). - A set of **client SDKs and editor integrations** that drive the engine: a Python client, a TypeScript client, an MCP server, and a VS Code extension backed by a shared shell-ui ([packages/client-python/src/rocketride/client.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-python/src/rocketride/client.py), [packages/client-typescript/src/client/client.ts](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-typescript/src/client/client.ts), [packages/client-mcp/src/rocketride_mcp/server.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-mcp/src/rocketride_mcp/server.py)). The project tagline — "Your code editor just became the AIDE" — captures the intent: the existing IDE is repurposed as the full AI Development Environment ([README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md)). ## Client SDKs ### Python client The Python client ([packages/client-python/src/rocketride/client.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-python/src/rocketride/client.py)) is the canonical way to drive a RocketRide pipeline from Python notebooks, scripts, or backend services. It speaks the engine's subprocess protocol and exposes pipeline lifecycle methods (load, run, send, close). ### TypeScript client The TypeScript client ([packages/client-typescript/src/client/client.ts](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-typescript/src/client/client.ts)) targets web and Node.js consumers. It is the bridge consumed by the VS Code extension's webview surface. ### MCP server The MCP server ([packages/client-mcp/src/rocketride_mcp/server.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-mcp/src/rocketride_mcp/server.py)) lets external AI agents — including Claude and other MCP-compatible tools — invoke RocketRide pipelines as tools. This makes any pipeline runnable as a callable function from a third-party agent. ## VS Code Extension & Shell-UI Integration The VS Code extension ([apps/vscode/src/extension.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/extension.ts)) is the flagship IDE surface. The latest automated prerelease of the **RocketRide VS Code Extension v1.2.0** is built from `develop` and published as a prerelease artifact. Internally the extension coordinates an **engine manager** ([apps/vscode/src/engine/engine-manager.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/engine/engine-manager.ts)) and an **engine registry** ([apps/vscode/src/engine/engine-registry.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/engine/engine-registry.ts)) that locate, spawn, and supervise the C++ engine subprocess. ### Document model The shared shell-ui implements a VS Code–style document model in [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx). Three core types describe the editor surface: | Type | Role | |---|---| | `Document` | One per URI; holds content in memory, tracks `dirty` and an incrementing `version` counter, plus `editorCount` and `isNew`. A `static` flag is used for monitor/webview documents that bypass VFS read/write. | | `Editor` | A view onto a `Document` with independent viewport state. | | `EditorGroup` | A pane container holding ordered editors and a split orientation. | Layouts are a recursive tree of `LayoutLeaf` and `LayoutSplit` nodes under a single `rootNode`, with `activeGroupId` tracking focus ([apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)). ### Workspace binding Documents integrate with the shell's workspace persistence through an optional `WorkspaceBinding` that exposes the current `appState` and an `updateAppState` setter. State is stored under the opaque key `documents` (`APPSTATE_KEY`) and written back with a 500 ms debounce (`PERSIST_DEBOUNCE_MS`) so rapid edits do not flood storage. When the binding is omitted the model works purely in memory. ```mermaid flowchart LR Editor[VS Code Extension] --> TSClient[TypeScript Client] MCP[MCP Server] --> PyClient[Python Client] TSClient --> EngineManager[Engine Manager] PyClient --> EngineManager EngineManager --> EngineRegistry[Engine Registry] EngineRegistry --> CppEngine[C++ Engine Subprocess] CppEngine --> Nodes[(Nodes: parser, chroma, agent, llamaparse, ...)] ShellUI[Shell-UI Documents] --> Workspace[(Workspace appState)] ``` ## Node Ecosystem Surface Clients ultimately drive a graph of nodes. The catalog includes: - **Parser** — extracts text, tables, images, audio, and video from arbitrary document bytes ([nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md)). - **Chroma** — vector-store node that also registers as a tool (`chroma.search`, `chroma.upsert`, `chroma.delete`) and supports `store` and `invoke` class types, so an agent in the same pipeline can call it directly ([nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md)). - **Agent LangChain** — agent node exposing `agent_description` and `instructions`, with a `profile` selector ([nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md)). Additional providers — **Landing.ai Parse/Extract**, **LlamaParse**, **Reducto**, **Firecrawl**, **Deepseek**, **Perplexity**, and the **preprocessor_langchain / preprocessor_code** nodes — all expose the same lane-based interface, so a client SDK interacts with them uniformly through lane names (`data`, `text`, `table`, `image`, `documents`, `answers`, `questions`). ## Known Integration Issues from the Community Three open issues are directly tied to the IDE/client experience: - **#1338 — Large-image decode/encode round-trips.** A ~30 MP image spends ~28–38 s in redundant full-resolution PNG decode/encode steps in the shared image path (dropper → parse → detect → response_image), even though model inference is only ~0.5 s. Clients sending large images should expect this overhead in `examples/vision.pipe` until the shared path is optimized. - **#1337 — Full trace inlines image bytes.** With `pipelineTraceLevel: 'full'`, the C++ engine inlines each node's full `model_dump()` payload — including raw image bytes — into `>DBG` FLOW-trace events. A single large image produces a subprocess→parent stdout line exceeding 16 MB, breaking trace consumers in the extension. - **#1335 — Dropper "Browse files" button.** Clicking the inline button inside the dropper component does nothing, while clicking the outer square opens the file picker. This is a UI regression in the shell-ui dropper that the VS Code extension surfaces to users. Each of these issues is observable from a client or IDE workflow, so they are part of the practical integration surface even though the root cause lives deeper in the engine or shell-ui layers. ## See Also - Engine & Pipeline Execution - Node Catalog (Parser, Chroma, LangChain, Landing.ai) - Workspace & Persistence Model --- ## Deployment, Observability & Operations ### Related Pages Related topics: [Repository Overview & System Architecture](#page-1), [Pipeline System, Nodes & Execution Model](#page-2), [SDKs, Clients & IDE Integration](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/llamaparse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llamaparse/README.md) - [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md) - [nodes/src/nodes/tool_firecrawl/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_firecrawl/README.md) - [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)
# Deployment, Observability & Operations ## Overview RocketRide positions itself as "the open source AIDE: the AI Development Environment," built around a "battle-tested, high-throughput C++ engine" with the explicit goal of letting users "compose, debug, observe, and deploy AI runtimes" — production-readiness is a first-class design concern, not an after-thought. The project ships as a layered system: a compiled C++ engine that hosts pipelines, a catalog of pluggable Python "nodes," and a TypeScript shell UI (VS Code extension and CLI) that drives the engine. Source: [README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md). Operationally this means there are three deployment surfaces to think about: the engine process, the Python node packages it loads, and the front-end that authors and inspects pipelines. ## Deployment Architecture ```mermaid flowchart LR UI[Shell UI
VS Code / CLI
TypeScript] Engine[C++ Engine
Pipeline Host
Trace + Flow] Nodes[Python Node Packages
Parser, LLM, Tools, Agents] External[(External Services
Chroma, LlamaParse, Landing.ai,
Firecrawl, GitHub, DeepL)] UI -->|opens .pipe, traces| Engine Engine -->|loads via services JSON| Nodes Nodes -->|SDK calls| External Engine -->|>DBG FLOW events| UI ``` The engine treats every capability as a discrete node discovered through `services..json` descriptors. For example, LlamaParse is loaded as a sub-package, while Landing.ai bundles two capabilities (`parse` and `extract`) under a single package root that shares `landing_ai_base.py` and a common `requirements.txt`. Source: [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md). Shared code and assets live at the package root so all sub-nodes import the same base client and icon — a layout designed for drop-in addition of future capabilities. Parser, by contrast, ships with **no configuration fields** at all, which makes it a zero-config building block that is safe to deploy in any pipeline without environment tuning. Source: [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md). ## Observability: Pipeline Trace Levels The C++ engine emits `>DBG` **FLOW-trace events** on the subprocess-to-parent stdout channel. Each node's entire `model_dump()` payload is inlined into these events by default at `pipelineTraceLevel: 'full'`. Community issue **#1337** ("Pipeline 'full' trace inlines image bytes into FLOW events") documents a real operational pitfall: a single high-resolution image inflates one stdout line past the 16 MB limit, truncating or corrupting the trace stream. The recommended mitigation — implied by the issue title and the engine's level-based design — is to use a less verbose trace level (e.g. `flow` or `off`) when payloads are expected to be large, or to gate raw byte payloads behind a level filter. This is the same reason community issue **#1338** calls out vision pipelines spending 28–38 seconds on redundant full-resolution PNG decode/encode round-trips when model inference itself is ~0.5 s: the shared image path is not currently optimized for tracing overhead, so observability tooling and operational throughput are coupled. Both issues are upstream-visible and underscore that trace configuration is part of production tuning, not a developer convenience. ## Node Lifecycle and Configuration Each node package follows a consistent deployment shape. The `landing_ai` package is illustrative: | Aspect | Pattern | |---|---| | Sub-nodes | `parse/`, `extract/` sub-packages loaded via `services..json` `path` field | | Shared code | `landing_ai_base.py`, `requirements.txt`, icon at package root | | Auth | Single `ROCKETRIDE_LANDING_AI_KEY` env variable consumed by both sub-nodes | | Profiles | Exposed via a hidden profile field (e.g. `summarization.profile`, `chroma.profile`) with a documented default | Source: [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md), [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md). Tool nodes follow a different operational contract: they expose no data lanes and instead register as **tool providers** invoked by an agent node. Firecrawl, for instance, registers `firecrawl.scrape_url` and `firecrawl.map_url` and creates its SDK client **once when the pipeline starts**; a non-empty `apikey` is required or startup fails. Source: [nodes/src/nodes/tool_firecrawl/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_firecrawl/README.md). This fail-fast-at-startup pattern is a deliberate operational guard: missing credentials surface as clear errors before any document is processed. ## Front-end Operations The shell UI manages pipelines the same way VS Code manages source files: a `Document` per URI with in-memory content, a monotonic `version` counter, a dirty bit, and an `editorCount` for lifecycle decisions. A `Document` is only disposed when no editor references it **and** it is clean — a guarantee that avoids losing unsaved pipeline edits during a session. Source: [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx). A `static` flag exists for documents that are not backed by the virtual file system (e.g. monitor or webview panels), which skip VFS read/write and never go dirty. This separation keeps the engine's runtime view decoupled from the editor's authoring state, so operational monitoring panels can be live without colliding with pipeline editing. ## Common Failure Modes - **Trace stream truncation (community #1337):** `pipelineTraceLevel: 'full'` inlines full payloads, including binary image data; switch to a lower level or filter binary lanes for high-MP workloads. - **Vision-pipeline latency (community #1338):** large images incur repeated full-resolution encode/decode in the shared image path; budget non-inference time when sizing vision SLAs. - **Dropper UI non-response (community #1335):** clicking the inner "Browse files" label inside the dropper component does not trigger the file picker; only the outer drop zone does. This is an authoring-time UX bug, but it affects how operators feed documents into pipelines and should be worked around by clicking the outer area until fixed. - **Tool-node startup failure:** Firecrawl and similar nodes fail the whole pipeline start if credentials are missing — surface `apikey` configuration in deploy manifests. ## See Also - Parser node reference - LlamaParse node reference - Landing.ai node package - Chroma vector store node - Agent (LangChain) node --- --- ## Pitfall Log Project: rocketride-org/rocketride-server Summary: Found 13 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/412 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1337 ## 3. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1338 ## 4. Runtime risk - Runtime risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1335 ## 5. Identity risk - Identity risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `pip install rocketride` - Evidence: identity.distribution | https://github.com/rocketride-org/rocketride-server ## 6. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/rocketride-org/rocketride-server ## 7. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/rocketride-org/rocketride-server ## 8. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/rocketride-org/rocketride-server ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/rocketride-org/rocketride-server ## 10. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/rocketride-org/rocketride-server ## 11. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1253 ## 12. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/rocketride-org/rocketride-server ## 13. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/rocketride-org/rocketride-server