# 🛠️ Contributing to OSSM Configurator

Thank you for your interest in contributing to the OSSM Configurator! This document provides a detailed guide on how to add new components, mods, remotes, and hardware to the system.

---

## 🏗️ Data Architecture Overview

The configurator's data is organized into several key directories within `website/src/data/`:

-   `common/`: Shared data like `colors.json` and `hardware.json`.
-   `components/`: Detailed definitions of physical parts (STLs, quantities, dependencies).
-   `config/`: Wizard configuration, including `options.json` which defines the UI structure.

---

## ➕ Adding a New Component (Mod, Remote, or Part)

Adding a component involves three main steps:
1.  Defining the physical parts in `components/`.
2.  Ensuring all required hardware exists in `common/hardware.json`.
3.  Linking the component into the wizard UI via `config/options.json`.

### Step 1: Define the Component
Components are defined as JSON objects. A component can use one of two structures:

#### A. Standard Component (e.g., `actuator.json`)
Used for fixed assemblies where all selected parts are gathered into a single list.

```json
{
  "my-new-mod": {
    "category": "Mods",
    "type": "mod",
    "printedParts": [
      {
        "id": "mod-part-a",
        "name": "Mod Part A",
        "filamentEstimate": 45.2,
        "timeEstimate": "1h30m",
        "colour": "primary",
        "required": true,
        "url": "https://github.com/Owner/Repo/blob/main/part-a.stl?raw=true"
      }
    ],
    "hardwareParts": [
      {
        "id": "hardware-fasteners-m3x8-shcs",
        "required": true,
        "quantity": 4,
        "relatedParts": ["mod-part-a"]
      }
    ]
  }
}
```

#### B. System-based Component (e.g., `remote.json`, `hinges.json`)
Used when a category has multiple distinct "systems" that a user chooses between.

```json
{
  "remotes": {
    "category": "Remote",
    "systems": {
      "my-custom-remote": {
        "name": "Custom Remote v1",
        "description": "A high-performance custom remote",
        "image": "/images/options/custom-remote.png",
        "bodyParts": [
          {
            "id": "remote-shell",
            "name": "Remote Shell",
            "url": "...",
            "required": true
          }
        ],
        "knobs": [
          { "id": "knob-standard", "name": "Standard Knob", "url": "..." }
        ],
        "hardwareParts": [
          { "id": "remote-hardware", "required": true }
        ]
      }
    }
  }
}
```

### Step 2: Register Hardware
If your component requires hardware not already in the system, add it to `website/src/data/common/hardware.json`:

```json
"fasteners": {
  "M3x12 SHCS": {
    "id": "hardware-fasteners-m3x12-shcs",
    "name": "M3x12 SHCS",
    "price": 0.15
  }
}
```

### Step 3: Add to the Wizard (options.json)
To make your part selectable, add its ID to the `sections` in `website/src/data/config/options.json`.

```json
"toyMounts": {
  "sections": {
    "myNewCategory": {
      "title": "My New Category",
      "componentIds": ["my-new-part-id"],
      "isMultiSelect": true
    }
  }
}
```

---

## 📦 The Vendor System

The configurator uses a script to "vendor" external files. This ensures that even if an upstream GitHub repo changes, our builds remain stable.

After adding a new component with a `url` field:
1.  Run the vendor script:
    ```bash
    python scripts/vendor_update.py
    ```
2.  The script will:
    - Download the file to the `vendor/` directory.
    - Calculate a checksum.
    - Pin it to the current commit SHA.
    - Update your component JSON with a `vendor` metadata block.

---

## 🖼️ Images & Assets

-   **Component Images**: Place images in `website/public/images/options/`.
-   **Naming**: Use the component `id` as the filename (e.g., `my-part-id.png`).
-   **Specs**: Transparent PNGs are preferred for a premium "floating" look.

---

## ✅ Contribution Checklist

1.  [ ] Component JSON added to `website/src/data/components/`.
2.  [ ] Hardware added to `common/hardware.json` (if new).
3.  [ ] ID added to `config/options.json`.
4.  [ ] `python scripts/vendor_update.py` executed.
5.  [ ] Verified that the part appears in the summary and correctly calculates hardware.
6.  [ ] (Optional) High-quality image added to `/public/images/options/`.