munchdev/ossm-configurator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Restructure data files into component-specific and common directories, add new UI components, and update project documentation.

Browse Source
This commit is contained in:
MunchDev-oss
2026-01-07 02:06:43 -05:00
parent 97d2b66f02
commit 5366865b4b
28 changed files with 1894 additions and 2051 deletions
Download Patch File Download Diff File Expand all files Collapse all files

626
README.md
View File

@@ -1,571 +1,111 @@
# OSSM Configurator
# 🛠️ OSSM Configurator
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 Version](https://img.shields.io/badge/version-0.0.1--beta-blue.svg)](https://github.com/KinkyMakers/OSSM-Configurator)
[![License](https://img.shields.io/badge/License-OSSM-green.svg)](https://github.com/KinkyMakers/OSSM-Configurator)
## 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:
1. **Select Motor** - Choose from available motor options (42AIM30, 57AIM30, iHSV57)
2. **Choose Power Supply** - Select appropriate power supply (24V PSU, 24V USB-C PD)
3. **Customize Colors** - Pick primary and accent colors for 3D printed parts
4. **Configure Options** - Select mounting options, stands, toy mounts, actuators, and other components
5. **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
- [X] 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
1. Navigate to the website directory:
```bash
cd website
```
2. Install dependencies:
```bash
npm install
```
### Development
Run the development server:
```bash
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:
```bash
npm run build
```
The built files will be in the `website/dist/` directory.
### Preview Production Build
Preview the production build locally:
```bash
npm run preview
```
## Docker Deployment
### Development with Docker Compose
Run the application in development mode with hot reload:
```bash
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):
```bash
docker-compose -f docker-compose-dev.yml up -d
```
To stop the development container:
```bash
docker-compose -f docker-compose-dev.yml down
```
### Production with Docker Compose
Build and run the production image:
```bash
docker-compose up --build -d
```
The application will be available at `http://localhost:80`
To run without rebuilding (if image already exists):
```bash
docker-compose up -d
```
To stop the production container:
```bash
docker-compose down
```
To view logs:
```bash
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:
```bash
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:
1. Update the appropriate JSON data files in `website/src/data/`
2. Add corresponding images to `website/public/images/`
3. Test the configuration flow to ensure compatibility
4. 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.
A professional web-based configuration tool for the **Open Source Sex Machine (OSSM)** project. This application provides a premium, intuitive wizard interface that guides users through the complex process of selecting, customizing, and validating components for their OSSM build.
---
## Vendor System
## 🌟 Key Features
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.
- **Intuitive Wizard Flow**: Step-by-step guidance from motor selection to final export.
- **Dynamic 3D Visualization (Coming Soon)**: Preview your build with real-time color updates.
- **Smart Compatibility**: Ensures your PSU matches your Motor and your Mount fits your Actuator.
- **Rich BOM Export**: Download a complete ZIP package containing:
- 📄 **README.md** overview of your build.
- 📊 **Excel BOM** for hardware ordering.
- 🖨️ **Print List** with filament estimates.
- 📁 **Organized STL Files** categorized by component and color.
- **Vendor System**: Integrated tracking for external CAD files to ensure reproducible builds.
- **Dark Mode Support**: A premium aesthetic designed for builders, day or night.
### 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
## 📸 Guided Walkthrough
### Project Structure (Vendor System)
### 1. Component Selection
The wizard starts with core hardware. Select your motor and power supply with real-time feedback on compatibility and cost.
![Motor Selection](./Screen%20Shots/Motor-Selected.png)
*Figure 1: Motor selection with clear technical specs and visual feedback.*
![PSU Selection](./Screen%20Shots/PSU%20selector.png)
*Figure 2: Choosing a compatible power supply (24V or USB-C PD).*
### 2. Aesthetic Customization
Choose your Primary and Accent colors. These selections automatically update the filament estimates in your final BOM.
![Color Selection](./Screen%20Shots/Color%20Selector.png)
*Figure 3: Interactive color picker for 3D printed components.*
### 3. Detailed Options
Configure every aspect of your machine, from the stand type to specialized toy mounts.
![Options Selection](./Screen%20Shots/Options%20List.png)
*Figure 4: Browsing the extensive list of compatible add-ons and variations.*
### 4. Final Summary & Export
Review your entire build, total cost, and total filament weight before exporting your build package.
![BOM Summary](./Screen%20Shots/Summary.png)
*Figure 5: The comprehensive BOM summary with automated ZIP generation.*
---
## 🚀 Getting Started
### Quick Start (Docker)
The easiest way to run the configurator locally:
```bash
docker-compose -f docker-compose-dev.yml up -d
```
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
```
Access the app at `http://localhost:5173`.
### Manifest Schema
The `manifest/vendor_manifest.json` file contains metadata for each vendored file:
```json
{
"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:**
```json
{
"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):**
```json
{
"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
1. **Install Python dependencies:**
### Local Development
1. **Clone the repo**
2. **Setup Website**:
```bash
cd website
npm install
npm run dev
```
3. **Setup Logic** (Optional, for vendor updates):
```bash
cd scripts
pip install -r requirements.txt
python vendor_update.py
```
2. **Set up GitHub API token:**
```bash
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
## 🗺️ Project Roadmap
### Local Usage
We are constantly improving the OSSM Configurator. Check out our **[detailed roadmap](./roadmap/ROADMAP.md)** for upcoming features, including:
- 🛠️ Interactive 3D Render/Preview
- 🌍 Multi-language & Multi-currency support
- 📦 Integrated assembly guides
#### 1. Generate Manifest from Site Data
---
Scan component JSON files and create/update the vendor manifest:
## 🤝 Contributing
```bash
python scripts/generate_manifest_from_site.py \
--site-dir website/src/data/components \
--manifest manifest/vendor_manifest.json
```
Contributions are welcome! Whether you are adding a new remote, a toy mount, or a hardware mod, please refer to our detailed guide:
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`)
👉 **[Read the CONTRIBUTING.md](./CONTRIBUTING.md)**
#### 2. Download and Pin Files
### Quick Summary:
1. Update JSON data in `website/src/data/`.
2. Add relevant images to `website/public/images/`.
3. Run `python scripts/vendor_update.py` for new files.
4. Submit a PR!
Download files from GitHub and pin them to commit SHAs:
---
```bash
# Update all entries
python scripts/vendor_update.py \
--manifest manifest/vendor_manifest.json
## 📜 License
# Update a specific entry
python scripts/vendor_update.py \
--manifest manifest/vendor_manifest.json \
--entry ossm-actuator-body-bottom
This project is part of the **Open Source Sex Machine (OSSM)** project. Please refer to the main OSSM project for full license details.
# 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:
```bash
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:
1. **Runs daily** (2 AM UTC) or can be triggered manually
2. **Generates manifest** from site data
3. **Checks for updates** in upstream repositories
4. **Creates a branch and PR** if updates are available
5. **Updates vendored files** and syncs metadata to component JSON files
#### Manual Trigger
To manually trigger the workflow:
1. Go to Actions tab in GitHub
2. Select "Check Vendor Updates" workflow
3. 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
1. **Deploy the webhook** (e.g., to a serverless platform, VPS, or local server)
2. **Configure webhook secret:**
```bash
export WEBHOOK_SECRET=your_webhook_secret_here
```
3. **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:
```bash
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:
```bash
# 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:
1. **Remove vendor fields** from component JSON files manually, or
2. **Restore from git history:**
```bash
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:
```bash
# 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
1. **Always pin to commit SHAs** (not branch names) for reproducible builds
2. **Run `check_updates.py` regularly** to detect upstream changes
3. **Review PRs** created by the GitHub Action before merging
4. **Test site builds** after vendor updates to ensure compatibility
5. **Keep manifest in version control** for tracking vendored files
### Example Workflow
Complete workflow for adding a new component with external files:
1. **Add component to site JSON:**
```json
{
"id": "new-part",
"url": "https://github.com/owner/repo/blob/main/file.stl?raw=true"
}
```
2. **Generate manifest:**
```bash
python scripts/generate_manifest_from_site.py
```
3. **Vendor the file:**
```bash
python scripts/vendor_update.py --entry new-part --sync-site
```
4. **Verify:**
```bash
python scripts/check_updates.py
```
The GitHub Action will automatically monitor for future updates.
---
*Built with ❤️ by the OSSM Community.*