Octopus — Architecture
Decision Framework
Use this framework to decide whether a given capability should be built as a workflow-mode execution node, a server group node, or both. Answer each question in order — the first definitive answer stops the decision tree.
The 10-Question Decision Guide
| # | Question | Yes → | No → |
|---|---|---|---|
| 1 | Does the capability require persistent in-memory state (loaded model, open connection, warm cache) between calls? | Server Node — workflow nodes are created/destroyed per run | Continue to Q2 |
| 2 | Will more than one workflow or agent need to call this capability concurrently? | Server Node — shared infrastructure, independently scalable | Continue to Q3 |
| 3 | Does the capability need to be deployed and updated independently of the main Octopus/workflow host? | Server Node — separate deployment unit | Continue to Q4 |
| 4 | Is this a sequential multi-step business process with branching, approvals, or human-in-the-loop steps? | Workflow Node — Flow Studio manages state and branching | Continue to Q5 |
| 5 | Does execution require access to the workflow's variable context (inputs from previous nodes, loop indices)? | Workflow Node — only workflow executors have INodeExecutionContext | Continue to Q6 |
| 6 | Is this capability rarely invoked (e.g. monthly batch, one-time migration)? | Workflow Node — no value in a persistent service for rare calls | Continue to Q7 |
| 7 | Does the capability require GPU or specialised hardware that must stay allocated? | Server Node — GPU nodes must stay resident | Continue to Q8 |
| 8 | Is throughput a concern (100+ calls/minute expected)? | Server Node — horizontal scaling via Server Group | Continue to Q9 |
| 9 | Do multiple Octopus deployments (dev, staging, prod, different tenants) need to share this capability? | Server Node — centralised shared service | Continue to Q10 |
| 10 | Is the capability simple enough to implement directly as an Octopus plugin tool? | Plugin Tool — implement as an MCPTool inside an IOctopusPlugin | Workflow Node — default fallback for contained logic |
Decision Summary
| Scenario | Recommended Approach |
|---|---|
| Invoice approval workflow with 5 sequential steps and a human approval gate | Workflow nodes (stateful, sequential, HIL) |
| LLM text summarisation used by 10 different workflows | Server node in "inference-cluster" Server Group |
| Real-time stock price lookup called by an Octopus agent | Octopus plugin tool (stateless, low latency, single-caller) |
| Browser automation with persistent session state | Server node (WebDriverPlugin is already a server node pattern) |
| PDF report generation triggered monthly | Workflow node (rare, no need for persistent service) |
| Embedding model called by 20 concurrent agents | Server node in "embedding-cluster" Server Group |
| Data validation step inside an ETL pipeline | Workflow node (sequential, inline, uses workflow context) |
| Zendesk ticket creation called from both workflows and agents | Server node MCP server (shareable, independently deployed) |
Using Both: Hybrid Architecture
Many production systems use both modes in combination. The workflow orchestrates the business process; the server nodes provide shared AI and integration capabilities that the workflow calls via HTTP.
┌─────────────────────────────────────────────────────┐
│ Flow Studio Workflow │
│ │
│ [Start] → [Validate Data] │
│ (workflow node) │
│ ↓ │
│ [Call Inference Server] │
│ (server group call) ────────────────────►│ inference-cluster
│ ↓ │ (server nodes)
│ [Human Review Gate] │
│ (HIL workflow node) │
│ ↓ │
│ [Create Zendesk Ticket] │
│ (server group call) ────────────────────►│ zendesk-mcp-server
│ ↓ │ (server node)
│ [End] │
└─────────────────────────────────────────────────────┘
Start with workflow nodes. For a new capability, start with a workflow node — it is simpler to build, test, and deploy. Promote to a server node only when you hit the real requirements: shared usage, persistent state, high throughput, or GPU allocation.