# pmndrs/react-three-rapier architecture

> Architecture diagram of the GitHub repository pmndrs/react-three-rapier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmndrs/react-three-rapier
- Repository: https://github.com/pmndrs/react-three-rapier

## Overview

##### Main Components
- Demo Application: Located under the “demo” directory. This layer is a stand-alone application that demonstrates various physics examples and interactions. It contains the main entry point (main.tsx), various example components (each in their subdirectories), and supporting files (like Vite configuration and tsconfig).
- react-three-rapier Library: Found in “packages/react-three-rapier”. This is the core package that provides React components (e.g., Debug, Physics, RigidBody), hooks, utilities, and types that abstract the low-level interactions with the underlying Rapier physics engine.
- react-three-rapier-addons: Found in “packages/react-three-rapier-addons”. This package contributes additional functionality (like attractors) that extends the core library.
- Underlying Physics Engine: Although not in the file tree per se, the library relies on the external Rapier physics engine. It may be abstracted behind some utility functions and hooks.
- Testing Layer: Located in packages/react-three-rapier/tests and possibly elsewhere for the demo. This shows how the library’s behavior is verified.
- Build & Configuration Tools: Includes configuration files (e.g., babel.config.js, commitlint.config.js, TS configs, Vite configs, GitHub workflows, etc.) that support development, testing, and deployment.

##### Relationships & Interactions
- The Demo application consumes the exported components and hooks from the “react-three-rapier” package and optionally from the “react-three-rapier-addons”, thereby demonstrating a separation of concerns between application code and library code.
- The core “react-three-rapier” package is designed to encapsulate the complexities of the Rapier physics engine while exposing high-level React components (such as Physics, RigidBody, InstancedRigidBodies, and a variety of collider components). This provides an easy integration point for end users.
- The “react-three-rapier-addons” package wraps or extends functionalities provided by the core package, offering additional or customized behavior (like attractor components with debug helpers).
- The testing layer interacts with the core library by simulating physics interactions, testing collider behavior, and ensuring interface integrity.

##### Architectural Patterns & Principles
- Modularity: The monorepo structure separates common concerns (core library vs. addons vs. demo) and allows each package to be developed, tested, and deployed independently.
- Component-based architecture: In line with React’s philosophy, most of the work is done through highly componentized building blocks.
- Abstraction and layering: The delicate separation between the low-level Rapier physics engine (abstracted away) and the high-level React components makes the system easier to maintain and extend.
- Clear boundaries with API contracts: The core package exposes a well-defined API (including hooks, components, and utilities) that can be reliably consumed by the demo or any downstream application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        Demo["Demo Application"]:::demoColor
    end

    subgraph "Library/Modules Layer"
        Core["Core Library (react-three-rapier)"]:::libraryColor
        Addons["Addons (react-three-rapier-addons)"]:::libraryColor
    end

    subgraph "External Dependencies"
        Rapier["Rapier Physics Engine"]:::externalColor
    end

    subgraph "Supporting Infrastructure"
        Tests["Testing Layer"]:::testingColor
        Build["Build & Config Tools"]:::configColor
    end

    %% Relationships
    Demo -->|"consumes"| Core
    Demo -->|"optionallyUses"| Addons
    Addons -->|"extends"| Core
    Core -->|"uses"| Rapier
    Addons -->|"uses"| Rapier
    Tests -->|"verifies"| Core
    Tests -->|"verifies"| Addons
    Build -->|"builds"| Demo
    Build -->|"builds"| Core
    Build -->|"builds"| Addons
    Build -->|"supports"| Tests

    %% Click Events
    click Demo "https://github.com/pmndrs/react-three-rapier/tree/main/demo/"
    click Core "https://github.com/pmndrs/react-three-rapier/tree/main/packages/react-three-rapiler/"
    click Addons "https://github.com/pmndrs/react-three-rapier/tree/main/packages/react-three-rapier-addons/"
    click Tests "https://github.com/pmndrs/react-three-rapier/tree/main/packages/react-three-rapier/tests/"
    click Build "https://github.com/pmndrs/react-three-rapier/blob/main/babel.config.js"

    %% Styles
    classDef demoColor fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef libraryColor fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef externalColor fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef testingColor fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef configColor fill:#FFD700,stroke:#000,stroke-width:2px;
```
