# inviscidai/openreynolds architecture

> Architecture diagram of the GitHub repository inviscidai/openreynolds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inviscidai/openreynolds
- Repository: https://github.com/inviscidai/openreynolds

## Overview

OpenReynolds is a CFD agent that uses a language-model tool loop to work in a real OpenFOAM workspace. The user describes a study; the agent chooses its own sequence of case-writing, meshing, solving, monitoring, inspection and file retrieval. A separate CAD agent can build and validate a mesh, and mesh review provides an independent check. The graph reflects documented capabilities and sampled module references; unsampled subsystem internals and some runtime wiring are represented only where the README supports them.

Main entry points: [`openreynolds/tools.py`](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/tools.py) (Tool handlers), [`openreynolds/backend/base.py`](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/base.py) (Backend interface), [`openreynolds/loop.py`](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/loop.py) (Agent loop), [`openreynolds/cad/agent.py`](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/agent.py) (CAD agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session and orchestration"]
  node_cli["CLI<br/>[cli.py]"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_modes["Study modes<br/>[modes.py]"]
end

subgraph group_agent["Agent and tools"]
  node_provider["Model provider<br/>[base.py]"]
  node_toolhandlers["Tool handlers<br/>[tools.py]"]
end

subgraph group_workspace["Workspace and execution"]
  node_backend["Backend interface<br/>[base.py]"]
  node_hosted["Hosted backend<br/>[hosted.py]"]
  node_local["Local backend<br/>[local.py]"]
  node_kernel["Persistent kernel<br/>[kernel.py]"]
end

subgraph group_cad["CAD and validation"]
  node_cadagent["CAD agent<br/>[agent.py]"]
  node_cadcheck["Mesh checks<br/>[check.py]"]
  node_review["Mesh review<br/>[review.py]"]
  node_preflight["Case preflight<br/>[preflight.py]"]
end

subgraph group_results["Monitoring and results"]
  node_store[("Session store<br/>[store.py]")]
  node_progress["Live progress<br/>[progress.py]"]
  node_mirror["Workspace mirror<br/>[mirror.py]"]
  node_browse["Workspace browser<br/>[browse.py]"]
  node_view["Session view<br/>[view.py]"]
  node_images["Image handling<br/>[images.py]"]
end

node_engineer(("Engineer"))
node_modelservice{{"Model API"}}
node_workspaceinstance{{"OpenFOAM workspace"}}

node_engineer -->|"starts study"| node_cli
node_cli -.->|"starts session"| node_loop
node_loop -->|"requests turns"| node_provider
node_provider -.->|"calls model"| node_modelservice
node_modelservice -.->|"returns tool calls"| node_provider
node_loop -->|"dispatches tools"| node_toolhandlers
node_loop -->|"uses modes"| node_modes
node_loop -->|"records session"| node_store
node_loop -->|"updates view"| node_view
node_toolhandlers -->|"runs workspace tools"| node_backend
node_backend -.->|"implemented by"| node_hosted
node_backend -.->|"implemented by"| node_local
node_hosted -->|"controls workspace"| node_workspaceinstance
node_local -.->|"runs locally"| node_workspaceinstance
node_toolhandlers -->|"delegates CAD"| node_cadagent
node_cadagent -->|"executes cells"| node_kernel
node_kernel -->|"uses workspace"| node_backend
node_cadagent -->|"validates mesh"| node_cadcheck
node_cadagent -->|"requests review"| node_review
node_toolhandlers -->|"offers diagnostics"| node_preflight
node_toolhandlers -->|"reports run status"| node_progress
node_progress -->|"reads run state"| node_backend
node_toolhandlers -->|"brings files home"| node_mirror
node_mirror -->|"copies workspace files"| node_backend
node_toolhandlers -->|"browses workspace"| node_browse
node_browse -->|"reads workspace"| node_backend
node_browse -->|"uses session data"| node_store
node_view -.->|"shows renders"| node_images

click node_cli "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cli.py"
click node_loop "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/loop.py"
click node_modes "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/modes.py"
click node_provider "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/llm/base.py"
click node_toolhandlers "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/tools.py"
click node_backend "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/base.py"
click node_hosted "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/hosted.py"
click node_local "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/local.py"
click node_kernel "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/kernel.py"
click node_cadagent "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/agent.py"
click node_cadcheck "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/check.py"
click node_review "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/review.py"
click node_preflight "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/toolbox/preflight.py"
click node_store "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/store.py"
click node_progress "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/progress.py"
click node_mirror "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/mirror.py"
click node_browse "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/browse.py"
click node_view "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/view.py"
click node_images "https://github.com/inviscidai/openreynolds/blob/main/openreynolds/images.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_loop,node_modes toneBlue
class node_provider,node_toolhandlers toneAmber
class node_backend,node_hosted,node_local,node_kernel,node_modelservice toneMint
class node_cadagent,node_cadcheck,node_review,node_preflight toneRose
class node_store,node_progress,node_mirror,node_browse,node_view,node_images,node_engineer,node_workspaceinstance toneIndigo
```

## Components

### Session and orchestration

- [CLI](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cli.py): `openreynolds/cli.py`
- [Agent loop](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/loop.py): `openreynolds/loop.py`
- [Study modes](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/modes.py): `openreynolds/modes.py`

### Agent and tools

- [Model provider](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/llm/base.py): `openreynolds/llm/base.py`
- [Tool handlers](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/tools.py): `openreynolds/tools.py`

### Workspace and execution

- [Backend interface](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/base.py): `openreynolds/backend/base.py`
- [Hosted backend](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/hosted.py): `openreynolds/backend/hosted.py`
- [Local backend](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/local.py): `openreynolds/backend/local.py`
- [Persistent kernel](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/backend/kernel.py): `openreynolds/backend/kernel.py`

### CAD and validation

- [CAD agent](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/agent.py): `openreynolds/cad/agent.py`
- [Mesh checks](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/check.py): `openreynolds/cad/check.py`
- [Mesh review](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/cad/review.py): `openreynolds/cad/review.py`
- [Case preflight](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/toolbox/preflight.py): `openreynolds/toolbox/preflight.py`

### Monitoring and results

- [Session store](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/store.py): `openreynolds/store.py`
- [Live progress](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/progress.py): `openreynolds/progress.py`
- [Workspace mirror](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/mirror.py): `openreynolds/mirror.py`
- [Workspace browser](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/browse.py): `openreynolds/browse.py`
- [Session view](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/view.py): `openreynolds/view.py`
- [Image handling](https://github.com/inviscidai/openreynolds/blob/main/openreynolds/images.py): `openreynolds/images.py`

### Other components

- **Engineer**
- **Model API**
- **OpenFOAM workspace**

## Connections

- Engineer → CLI: starts study
- CLI → Agent loop: starts session (evidence: `openreynolds/cli.py`)
- Agent loop → Model provider: requests turns (evidence: `openreynolds/loop.py`)
- Model provider → Model API: calls model
- Model API → Model provider: returns tool calls
- Agent loop → Tool handlers: dispatches tools (evidence: `openreynolds/loop.py`)
- Agent loop → Study modes: uses modes (evidence: `openreynolds/loop.py`)
- Agent loop → Session store: records session (evidence: `openreynolds/loop.py`)
- Agent loop → Session view: updates view (evidence: `openreynolds/loop.py`)
- Tool handlers → Backend interface: runs workspace tools (evidence: `openreynolds/tools.py`)
- Backend interface → Hosted backend: implemented by (evidence: `openreynolds/backend/hosted.py`)
- Backend interface → Local backend: implemented by (evidence: `openreynolds/backend/local.py`)
- Hosted backend → OpenFOAM workspace: controls workspace
- Local backend → OpenFOAM workspace: runs locally
- Tool handlers → CAD agent: delegates CAD (evidence: `openreynolds/tools.py`)
- CAD agent → Persistent kernel: executes cells (evidence: `openreynolds/cad/agent.py`)
- Persistent kernel → Backend interface: uses workspace (evidence: `openreynolds/backend/kernel.py`)
- CAD agent → Mesh checks: validates mesh (evidence: `openreynolds/cad/agent.py`)
- CAD agent → Mesh review: requests review (evidence: `openreynolds/cad/agent.py`)
- Tool handlers → Case preflight: offers diagnostics
- Tool handlers → Live progress: reports run status (evidence: `openreynolds/tools.py`)
- Live progress → Backend interface: reads run state (evidence: `openreynolds/progress.py`)
- Tool handlers → Workspace mirror: brings files home
- Workspace mirror → Backend interface: copies workspace files (evidence: `openreynolds/mirror.py`)
- Tool handlers → Workspace browser: browses workspace
- Workspace browser → Backend interface: reads workspace (evidence: `openreynolds/browse.py`)
- Workspace browser → Session store: uses session data (evidence: `openreynolds/browse.py`)
- Session view → Image handling: shows renders