# amirbehbahanian/simulator architecture

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

- Interactive diagram: https://gitdiagram.com/amirbehbahanian/simulator
- Repository: https://github.com/amirbehbahanian/simulator

## Overview

JEV Simulator turns point-cloud scene inputs into a rigid-body simulation, then exports step data for interactive playback or video. The principal workflow is CLI orchestration → scene loading → broad/narrow collision processing → contact response and integration → penetration-controlled timestep acceptance → export and visualization. Jev is the optional remote narrow-phase classifier; proximity is an offline alternative. The graph follows the documented world pipeline and sampled call sites; less-visible wiring is omitted where evidence is limited.

Main entry points: [`app/src/physics/world.py`](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/world.py) (World coordinator), [`app/src/main.py`](https://github.com/amirbehbahanian/simulator/blob/main/app/src/main.py) (Simulation runner), [`app/src/jev/detector.py`](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/detector.py) (Jev detector), [`app/src/physics/rigid_body.py`](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/rigid_body.py) (Rigid body state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run orchestration"]
  node_main["Simulation runner<br/>[main.py]"]
  node_scene["Scene loading<br/>[scene_io.py]"]
end

subgraph group_physics["Physics engine"]
  node_world["World coordinator<br/>[world.py]"]
  node_broad["Broad phase<br/>[broad_phase.py]"]
  node_contact["Contact generation<br/>[contact.py]"]
  node_resolver["Impulse resolution<br/>[resolver.py]"]
  node_integrator["Motion integration<br/>[integrator.py]"]
  node_timestep["Adaptive timestep<br/>[timestep.py]"]
  node_rigid["Rigid body state<br/>[rigid_body.py]"]
  node_metrics["Step metrics<br/>[metrics.py]"]
end

subgraph group_jev["Collision classification"]
  node_detector["Jev detector<br/>[detector.py]"]
  node_encoder["Pair encoder<br/>[encoder.py]"]
  node_interface["Detector interface<br/>[interface.py]"]
  node_client["TypeSafe client<br/>[client.py]"]
  node_jevconfig["Jev configuration<br/>[config.py]"]
  node_proximity["Proximity detector<br/>[mock.py]"]
end

subgraph group_outputs["Results and playback"]
  node_export["Run export<br/>[export.py]"]
  node_postprocess["Viewer generation<br/>[postprocess.py]"]
  node_video["Video rendering<br/>[render_video.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_geometry["Geometry operations<br/>[geometry.py]"]
  node_serialization["Serialization helpers<br/>[serialization.py]"]
  node_tensor["Tensor conventions<br/>[tensor_ops.py]"]
  node_transforms["Rigid transforms<br/>[transforms.py]"]
  node_env["Secret loading<br/>[env.py]"]
end

node_user(("CLI user"))
node_typesafe(("TypeSafe System One"))

node_user -->|"runs"| node_main
node_main -->|"loads scene"| node_scene
node_scene -->|"creates bodies"| node_rigid
node_main -->|"runs simulation"| node_world
node_main -->|"selects detector"| node_detector
node_main -->|"selects offline"| node_proximity
node_world -->|"finds candidates"| node_broad
node_world -->|"classifies pairs"| node_detector
node_world -->|"generates contacts"| node_contact
node_world -->|"integrates velocity"| node_integrator
node_world -->|"resolves impulses"| node_resolver
node_world -->|"controls retries"| node_timestep
node_world -->|"records metrics"| node_metrics
node_detector -->|"encodes pairs"| node_encoder
node_detector -->|"requests decisions"| node_client
node_detector -->|"implements"| node_interface
node_proximity -->|"implements"| node_interface
node_client -->|"uses settings"| node_jevconfig
node_client -->|"sends requests"| node_typesafe
node_jevconfig -->|"loads credentials"| node_env
node_main -->|"writes results"| node_export
node_main -->|"builds viewer"| node_postprocess
node_export -->|"serializes data"| node_serialization
node_postprocess -->|"reads step data"| node_export
node_video -->|"reuses processing"| node_postprocess
node_contact -->|"measures contact"| node_geometry
node_rigid -->|"derives bounds"| node_geometry
node_rigid -->|"transforms points"| node_transforms
node_geometry -->|"uses operations"| node_tensor
node_transforms -->|"uses conventions"| node_tensor

click node_main "https://github.com/amirbehbahanian/simulator/blob/main/app/src/main.py"
click node_scene "https://github.com/amirbehbahanian/simulator/blob/main/app/src/scene_io.py"
click node_world "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/world.py"
click node_broad "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/broad_phase.py"
click node_contact "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/contact.py"
click node_resolver "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/resolver.py"
click node_integrator "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/integrator.py"
click node_timestep "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/timestep.py"
click node_rigid "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/rigid_body.py"
click node_metrics "https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/metrics.py"
click node_detector "https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/detector.py"
click node_encoder "https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/encoder.py"
click node_interface "https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/interface.py"
click node_client "https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/client.py"
click node_jevconfig "https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/config.py"
click node_proximity "https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/mock.py"
click node_export "https://github.com/amirbehbahanian/simulator/blob/main/app/src/export.py"
click node_postprocess "https://github.com/amirbehbahanian/simulator/blob/main/app/src/postprocess.py"
click node_video "https://github.com/amirbehbahanian/simulator/blob/main/app/src/render_video.py"
click node_geometry "https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/geometry.py"
click node_serialization "https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/serialization.py"
click node_tensor "https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/tensor_ops.py"
click node_transforms "https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/transforms.py"
click node_env "https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/env.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_main,node_scene,node_user toneBlue
class node_world,node_broad,node_contact,node_resolver,node_integrator,node_timestep,node_rigid,node_metrics toneAmber
class node_detector,node_encoder,node_interface,node_client,node_jevconfig,node_proximity toneMint
class node_export,node_postprocess,node_video toneRose
class node_geometry,node_serialization,node_tensor,node_transforms,node_env,node_typesafe toneIndigo
```

## Components

### Run orchestration

- [Simulation runner](https://github.com/amirbehbahanian/simulator/blob/main/app/src/main.py): `app/src/main.py`
- [Scene loading](https://github.com/amirbehbahanian/simulator/blob/main/app/src/scene_io.py): `app/src/scene_io.py`

### Physics engine

- [World coordinator](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/world.py): `app/src/physics/world.py`
- [Broad phase](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/broad_phase.py): `app/src/physics/broad_phase.py`
- [Contact generation](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/contact.py): `app/src/physics/contact.py`
- [Impulse resolution](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/resolver.py): `app/src/physics/resolver.py`
- [Motion integration](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/integrator.py): `app/src/physics/integrator.py`
- [Adaptive timestep](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/timestep.py): `app/src/physics/timestep.py`
- [Rigid body state](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/rigid_body.py): `app/src/physics/rigid_body.py`
- [Step metrics](https://github.com/amirbehbahanian/simulator/blob/main/app/src/physics/metrics.py): `app/src/physics/metrics.py`

### Collision classification

- [Jev detector](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/detector.py): `app/src/jev/detector.py`
- [Pair encoder](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/encoder.py): `app/src/jev/encoder.py`
- [Detector interface](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/interface.py): `app/src/jev/interface.py`
- [TypeSafe client](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/client.py): `app/src/jev/client.py`
- [Jev configuration](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/config.py): `app/src/jev/config.py`
- [Proximity detector](https://github.com/amirbehbahanian/simulator/blob/main/app/src/jev/mock.py): `app/src/jev/mock.py`

### Results and playback

- [Run export](https://github.com/amirbehbahanian/simulator/blob/main/app/src/export.py): `app/src/export.py`
- [Viewer generation](https://github.com/amirbehbahanian/simulator/blob/main/app/src/postprocess.py): `app/src/postprocess.py`
- [Video rendering](https://github.com/amirbehbahanian/simulator/blob/main/app/src/render_video.py): `app/src/render_video.py`

### Shared foundations

- [Geometry operations](https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/geometry.py): `app/src/utils/geometry.py`
- [Serialization helpers](https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/serialization.py): `app/src/utils/serialization.py`
- [Tensor conventions](https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/tensor_ops.py): `app/src/utils/tensor_ops.py`
- [Rigid transforms](https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/transforms.py): `app/src/utils/transforms.py`
- [Secret loading](https://github.com/amirbehbahanian/simulator/blob/main/app/src/utils/env.py): `app/src/utils/env.py`

### Other components

- **CLI user**
- **TypeSafe System One**

## Connections

- CLI user → Simulation runner: runs (evidence: `README.md`)
- Simulation runner → Scene loading: loads scene (evidence: `app/src/main.py`)
- Scene loading → Rigid body state: creates bodies (evidence: `app/src/scene_io.py`)
- Simulation runner → World coordinator: runs simulation (evidence: `app/src/main.py`)
- Simulation runner → Jev detector: selects detector (evidence: `app/src/main.py`)
- Simulation runner → Proximity detector: selects offline (evidence: `app/src/main.py`)
- World coordinator → Broad phase: finds candidates (evidence: `app/src/physics/world.py`)
- World coordinator → Jev detector: classifies pairs (evidence: `app/src/physics/world.py`)
- World coordinator → Contact generation: generates contacts (evidence: `app/src/physics/world.py`)
- World coordinator → Motion integration: integrates velocity (evidence: `app/src/physics/world.py`)
- World coordinator → Impulse resolution: resolves impulses (evidence: `app/src/physics/world.py`)
- World coordinator → Adaptive timestep: controls retries (evidence: `app/src/physics/world.py`)
- World coordinator → Step metrics: records metrics (evidence: `app/src/physics/world.py`)
- Jev detector → Pair encoder: encodes pairs (evidence: `app/src/jev/detector.py`)
- Jev detector → TypeSafe client: requests decisions (evidence: `app/src/jev/detector.py`)
- Jev detector → Detector interface: implements (evidence: `app/src/jev/detector.py`)
- Proximity detector → Detector interface: implements (evidence: `app/src/jev/mock.py`)
- TypeSafe client → Jev configuration: uses settings (evidence: `app/src/jev/client.py`)
- TypeSafe client → TypeSafe System One: sends requests (evidence: `app/src/jev/client.py`)
- Jev configuration → Secret loading: loads credentials (evidence: `app/src/jev/config.py`)
- Simulation runner → Run export: writes results (evidence: `app/src/main.py`)
- Simulation runner → Viewer generation: builds viewer (evidence: `app/src/main.py`)
- Run export → Serialization helpers: serializes data (evidence: `app/src/export.py`)
- Viewer generation → Run export: reads step data (evidence: `app/src/postprocess.py`)
- Video rendering → Viewer generation: reuses processing (evidence: `app/src/render_video.py`)
- Contact generation → Geometry operations: measures contact (evidence: `app/src/physics/contact.py`)
- Rigid body state → Geometry operations: derives bounds (evidence: `app/src/physics/rigid_body.py`)
- Rigid body state → Rigid transforms: transforms points (evidence: `app/src/physics/rigid_body.py`)
- Geometry operations → Tensor conventions: uses operations (evidence: `app/src/utils/geometry.py`)
- Rigid transforms → Tensor conventions: uses conventions (evidence: `app/src/utils/transforms.py`)
