A web-based configuration tool for the Open Source Sex Machine (OSSM) project. This application provides an intuitive wizard interface that guides users through selecting and customizing components for their OSSM build, generating a complete Bill of Materials (BOM) and configuration summary.

Project Structure

OSSM-Configurator/
├── website/              # Main web application
│   ├── src/             # React source code
│   ├── public/          # Static assets (images, etc.)
│   ├── dist/            # Build output (generated)
│   ├── node_modules/    # Dependencies (generated)
│   └── ...              # Configuration files
├── BOM.xlsx             # Bill of Materials spreadsheet
├── Screen Shots/        # Application screenshots
└── README.md           # This file

Website Overview

The OSSM Configurator is a React-based single-page application built with Vite. It provides a step-by-step wizard interface that allows users to:

Select Motor - Choose from available motor options (42AIM30, 57AIM30, iHSV57)
Choose Power Supply - Select appropriate power supply (24V PSU, 24V USB-C PD)
Customize Colors - Pick primary and accent colors for 3D printed parts
Configure Options - Select mounting options, stands, toy mounts, actuators, and other components
Review Summary - View complete BOM with pricing, filament estimates, and export options

Key Features

Interactive Wizard Interface: Step-by-step configuration process with progress tracking
Component Compatibility: Ensures selected components are compatible with each other
Real-time Pricing: Calculates total cost including hardware and printed parts
Filament Estimates: Provides 3D printing filament requirements for each component
BOM Export: Generate and download a complete Bill of Materials
Visual Component Selection: Image-based component selection for better user experience

Technology Stack

React 18 - UI framework
Vite - Build tool and dev server
Tailwind CSS - Styling
JSZip - For generating downloadable BOM packages

TODO

Dark Mode [Completed]
Finalize Actuator Components and mapping to BOM [In Progress]
Finalize Stand Components and mapping to BOM
Finalize PCB Components and mapping to BOM
Finalize Toy Mounts Components and mapping to BOM
Finalize Remote Control Components and mapping to BOM
Finalize Mounting Components and mapping to BOM
Finalize Other Components and mapping to BOM
Finalize Colors and mapping to BOM
Finalize Pricing and mapping to BOM
Finalize BOM Export and mapping to BOM
Finalize BOM Import and mapping to BOM
Finalize Storage and sharing of BOMs
Add references to original hardware files and designs
Add Readme/assembly instructions for each component
Add FAQ and troubleshooting guide
Add support for multiple languages
Add support for multiple currencies
Add support for multiple payment methods
Add support for multiple shipping methods
Add support for multiple shipping countries
Add support for multiple shipping regions
Add support for multiple shipping cities
Add 3D render of final product with all components and options selected and coloured [If possible]

Getting Started

Prerequisites

Option 1: Using Docker (Recommended)

Docker Desktop or Docker Engine
Docker Compose

Option 2: Local Development

Node.js (v16 or higher recommended)
npm or yarn

Installation

Navigate to the website directory:
```
cd website
```
Install dependencies:
```
npm install
```

Development

Run the development server:

npm run dev

The application will be available at http://localhost:5173 (or the port shown in the terminal).

Building for Production

Create an optimized production build:

npm run build

The built files will be in the website/dist/ directory.

Preview Production Build

Preview the production build locally:

npm run preview

Docker Deployment

Development with Docker Compose

Run the application in development mode with hot reload:

docker-compose -f docker-compose-dev.yml up

The application will be available at http://localhost:5173 with hot module replacement enabled.

To run in detached mode (background):

docker-compose -f docker-compose-dev.yml up -d

To stop the development container:

docker-compose -f docker-compose-dev.yml down

Production with Docker Compose

Build and run the production image:

docker-compose up --build -d

The application will be available at http://localhost:80

To run without rebuilding (if image already exists):

docker-compose up -d

To stop the production container:

docker-compose down

To view logs:

docker-compose logs -f

Using Pre-built Docker Images

The project includes GitHub Actions workflows that automatically build and publish Docker images to GitHub Container Registry (ghcr.io) on releases. You can pull and run the latest release image:

docker pull ghcr.io/<your-username>/<your-repo-name>:V0.0.1-BETA
docker run -d -p 80:80 ghcr.io/<your-username>/<your-repo-name>:V0.0.1-BETA

Configuration Data

The application uses JSON data files located in website/src/data/:

motors.json - Available motor options
powerSupplies.json - Power supply options
colors.json - Available color options
options.json - Main configuration options
components/ - Detailed component data:
- actuator.json - Actuator components
- mounting.json - Mounting options
- remote.json - Remote control components
- stand.json - Stand components
- toyMounts.json - Toy mount options

Project Purpose

The OSSM Configurator serves as a comprehensive tool for users building their own Open Source Sex Machine. It simplifies the configuration process by:

Guiding Selection: Step-by-step wizard prevents missing critical components
Ensuring Compatibility: Validates component combinations
Providing Transparency: Shows costs, filament requirements, and time estimates
Generating Documentation: Creates exportable BOM for ordering parts and printing

This tool is essential for both beginners and experienced builders who want to ensure they have all necessary components and understand the full scope of their build before starting.

Contributing

When adding new components or options:

Update the appropriate JSON data files in website/src/data/
Add corresponding images to website/public/images/
Test the configuration flow to ensure compatibility
Update component pricing and filament estimates as needed

License

This project is part of the Open Source Sex Machine (OSSM) project. Please refer to the OSSM project license for usage terms.

Vendor System

The OSSM Configurator includes a robust vendoring and monitoring system for external asset files (STL files, etc.) referenced in component JSON files. This system ensures reproducible builds by pinning external files to specific commit SHAs and automatically detecting when upstream changes occur.

Overview

The vendor system:

Vendors external files from GitHub repositories into the vendor/ directory
Pins files to specific commit SHAs for reproducible builds
Monitors upstream repositories for changes
Automatically updates vendored files when upstream changes are detected
Preserves backward compatibility by keeping original url fields in component JSON files

Project Structure (Vendor System)

OSSM-Configurator/
├── manifest/
│   └── vendor_manifest.json    # Canonical list of vendored files
├── vendor/                     # Vendored file copies
│   └── owner-repo/            # Organized by repository
│       └── path/to/file.stl
├── scripts/
│   ├── generate_manifest_from_site.py  # Generate manifest from component JSONs
│   ├── vendor_update.py               # Download and pin files
│   └── check_updates.py               # Monitor upstream changes
├── api/
│   └── github_webhook/
│       └── index.py            # Webhook handler for push events
├── tests/
│   ├── test_vendor_update.py   # Tests for vendor_update.py
│   └── test_check_updates.py   # Tests for check_updates.py
└── .github/
    └── workflows/
        └── check-vendor.yml    # Automated monitoring workflow

Manifest Schema

The manifest/vendor_manifest.json file contains metadata for each vendored file:

{
  "id": "unique-id-or-slug",
  "source_repo": "owner/repo",
  "source_path": "path/in/repo/file.stl",
  "source_ref": "main",
  "pinned_sha": "commit-sha-currently-pinned",
  "pinned_raw_url": "https://raw.githubusercontent.com/owner/repo/<sha>/path/to/file.stl",
  "local_path": "vendor/owner-repo/path/to/file.stl",
  "checksum_sha256": "sha256-hex-digest",
  "last_checked": "2024-01-05T12:00:00Z",
  "upstream_latest_sha": "latest-commit-sha-observed",
  "status": "up-to-date | out-of-date | unknown",
  "license": "SPDX-identifier-or-URL",
  "orig_site_json": "website/src/data/components/actuator.json",
  "orig_item_id": "ossm-actuator-body-bottom"
}

Integration with Component JSON Files

The vendor system adds a vendor object to each printedParts entry in component JSON files, while preserving the original url field for backward compatibility:

Before:

{
  "id": "ossm-actuator-body-bottom",
  "name": "Actuator Bottom",
  "filePath": "OSSM - Actuator Body Bottom.stl",
  "url": "https://github.com/KinkyMakers/OSSM-hardware/.../file.stl?raw=true"
}

After (with vendor metadata):

{
  "id": "ossm-actuator-body-bottom",
  "name": "Actuator Bottom",
  "filePath": "OSSM - Actuator Body Bottom.stl",
  "url": "https://github.com/KinkyMakers/OSSM-hardware/.../file.stl?raw=true",
  "vendor": {
    "manifest_id": "ossm-actuator-body-bottom",
    "local_path": "vendor/KinkyMakers-OSSM-hardware/Printed Parts/Actuator/file.stl",
    "pinned_sha": "abc123...",
    "pinned_raw_url": "https://raw.githubusercontent.com/KinkyMakers/OSSM-hardware/abc123/...",
    "checksum_sha256": "deadbeef...",
    "last_checked": "2024-01-05T12:00:00Z",
    "status": "up-to-date"
  }
}

The website continues to use printedParts.url by default. Site code can optionally prefer vendor.* fields when available for offline hosting or improved reliability.

Prerequisites

Python 3.11 or higher
GitHub API token (for authenticated requests and higher rate limits)

Setup

Install Python dependencies:

cd scripts
pip install -r requirements.txt

Set up GitHub API token:
```
export GITHUB_API_TOKEN=your_token_here
# Or use GITHUB_TOKEN as fallback
```
To create a GitHub token:
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Generate a new token with public_repo scope (or repo for private repos)
- Required permissions: Read access to repositories

Local Usage

1. Generate Manifest from Site Data

Scan component JSON files and create/update the vendor manifest:

python scripts/generate_manifest_from_site.py \
  --site-dir website/src/data/components \
  --manifest manifest/vendor_manifest.json

This script:

Scans all JSON files in website/src/data/components/
Extracts printedParts entries with GitHub URLs
Creates manifest entries for each GitHub-hosted file
Supports nested structures (e.g., systems.printedParts, bodyParts, knobs)

2. Download and Pin Files

Download files from GitHub and pin them to commit SHAs:

# Update all entries
python scripts/vendor_update.py \
  --manifest manifest/vendor_manifest.json

# Update a specific entry
python scripts/vendor_update.py \
  --manifest manifest/vendor_manifest.json \
  --entry ossm-actuator-body-bottom

# Dry run (see what would be done)
python scripts/vendor_update.py \
  --manifest manifest/vendor_manifest.json \
  --dry-run

# Update and sync vendor metadata to site JSON files
python scripts/vendor_update.py \
  --manifest manifest/vendor_manifest.json \
  --sync-site

This script:

Resolves commit SHAs for the specified ref (branch/tag)
Downloads files from pinned URLs
Computes SHA256 checksums
Updates manifest with metadata
Optionally syncs vendor metadata back to component JSON files

3. Check for Upstream Updates

Monitor upstream repositories for changes:

python scripts/check_updates.py \
  --manifest manifest/vendor_manifest.json \
  --output report.json

This script:

Queries GitHub API for latest commit SHAs
Compares with pinned SHAs
Generates a report of up-to-date and out-of-date entries
Exits with non-zero code if any entries are out-of-date (useful for CI)

GitHub Action Workflow

The .github/workflows/check-vendor.yml workflow automatically:

Runs daily (2 AM UTC) or can be triggered manually
Generates manifest from site data
Checks for updates in upstream repositories
Creates a branch and PR if updates are available
Updates vendored files and syncs metadata to component JSON files

Manual Trigger

To manually trigger the workflow:

Go to Actions tab in GitHub
Select "Check Vendor Updates" workflow
Click "Run workflow"

Required Secrets

Configure these secrets in GitHub repository settings:

GITHUB_API_TOKEN: GitHub personal access token with public_repo scope

The workflow uses GITHUB_TOKEN for creating PRs (automatically provided by GitHub Actions).

Webhook Configuration

The api/github_webhook/index.py provides a Flask-based webhook handler that can receive push events from upstream repositories.

Setup

Deploy the webhook (e.g., to a serverless platform, VPS, or local server)

Configure webhook secret:

export WEBHOOK_SECRET=your_webhook_secret_here

Add webhook to upstream repository:
- Go to repository Settings → Webhooks → Add webhook
- Payload URL: https://your-domain.com/webhook
- Content type: application/json
- Secret: (same as WEBHOOK_SECRET)
- Events: Select "Just the push event"
- Active: ✓

Local Testing

Run the webhook locally for testing:

export WEBHOOK_SECRET=test_secret
export FLASK_DEBUG=true
python api/github_webhook/index.py

The webhook will:

Verify GitHub signature using X-Hub-Signature-256
Process push events
Identify affected manifest entries
Trigger update checks for changed files

Running Tests

Run the test suite:

# Install test dependencies
pip install -r scripts/requirements.txt

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_vendor_update.py -v
pytest tests/test_check_updates.py -v

Tests use pytest with responses for mocking HTTP requests to GitHub API.

URL Format Support

The vendor system supports multiple GitHub URL formats:

https://github.com/owner/repo/blob/main/path/to/file.stl?raw=true
https://github.com/owner/repo/raw/main/path/to/file.stl
https://raw.githubusercontent.com/owner/repo/main/path/to/file.stl

The system automatically:

Extracts owner, repo, path, and ref from URLs
Defaults to main branch if ref is missing
Handles URL-encoded paths

Reverting Vendor Changes

To revert vendor metadata from component JSON files:

Remove vendor fields from component JSON files manually, or

Restore from git history:

git checkout HEAD -- website/src/data/components/

The original url fields are never removed, so the site continues to work even if vendor metadata is removed.

Inspecting Vendor Status

View the current vendor status:

# Check manifest
cat manifest/vendor_manifest.json | jq '.[] | {id, status, pinned_sha, upstream_latest_sha}'

# Check for updates
python scripts/check_updates.py --manifest manifest/vendor_manifest.json

Troubleshooting

Issue: Rate limit errors from GitHub API

Solution: Set GITHUB_API_TOKEN environment variable with a personal access token

Issue: File not found at ref

Solution: The script will try the default branch if the specified ref doesn't exist

Issue: Webhook signature verification fails

Solution: Ensure WEBHOOK_SECRET matches the secret configured in GitHub webhook settings

Issue: Manifest entries not found

Solution: Run generate_manifest_from_site.py to create/update manifest entries

Best Practices

Always pin to commit SHAs (not branch names) for reproducible builds
Run check_updates.py regularly to detect upstream changes
Review PRs created by the GitHub Action before merging
Test site builds after vendor updates to ensure compatibility
Keep manifest in version control for tracking vendored files

Example Workflow

Complete workflow for adding a new component with external files:

Add component to site JSON:

{
  "id": "new-part",
  "url": "https://github.com/owner/repo/blob/main/file.stl?raw=true"
}

Generate manifest:

python scripts/generate_manifest_from_site.py

Vendor the file:

python scripts/vendor_update.py --entry new-part --sync-site

Verify:
```
python scripts/check_updates.py
```

The GitHub Action will automatically monitor for future updates.