📦 MakerStash

Your personal stash for 3D models

A powerful 3D model file manager for makers and 3D printing enthusiasts. Organize, view, and manage your STL, OBJ, and 3MF files with an intuitive web interface featuring interactive 3D previews and automatic thumbnail generation.

Browse, organize, and view your 3D models in an intuitive interface

Features

• Interactive 3D Viewer - View and rotate STL, OBJ, and 3MF models directly in the browser with Three.js
• Automatic Thumbnails - Auto-generated isometric preview images for STL, OBJ, and 3MF files
• Browse & Organize - View and manage your 3D model collection with an intuitive interface
• Collections - Group related models together for better organization
• Tags - Categorize models with custom tags and colors
• Search - Quickly find models by name, description, creator, or tags
• Metadata Management - Add descriptions, creator info, source URLs, notes, and support status
• File Support - Upload STL, OBJ, 3MF, GCODE, and ZIP files
• User Authentication - Secure registration and login system
• Responsive Design - Works on desktop, tablet, and mobile devices

Tech Stack

• Backend: Node.js, Express
• Database: SQLite3
• Frontend: Vanilla JavaScript, HTML5, CSS3
• 3D Visualization: Three.js with STLLoader and OBJLoader
• File Uploads: Multer
• Authentication: JWT, bcrypt

Prerequisites

• Node.js 16 or higher
• npm or yarn

Installation

1. Clone or download this repository

2. Install dependencies:

cd makerstash
npm install

3. Create a .env file in the root directory (or copy from .env.example):

PORT=3000
DATABASE_PATH=./database.sqlite
UPLOAD_DIR=./uploads
JWT_SECRET=your-secret-key-change-this
SESSION_SECRET=your-session-secret-change-this
NODE_ENV=development

Important: Change the JWT_SECRET and SESSION_SECRET to random, secure values in production!

Usage

Development Mode

Run the server with auto-reload:

npm run dev

Production Mode

Run the server:

npm start

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

Project Structure

makerstash/
├── server/
│   ├── database.js          # Database setup and schema
│   ├── index.js             # Express server entry point
│   ├── middleware/
│   │   └── auth.js          # Authentication middleware
│   ├── routes/
│   │   ├── auth.js          # Authentication endpoints
│   │   ├── models.js        # Model CRUD endpoints
│   │   ├── collections.js   # Collection endpoints
│   │   └── tags.js          # Tag endpoints
│   └── services/
│       └── thumbnailGenerator.js  # 3D model thumbnail generation
├── client/
│   ├── index.html           # Main HTML file
│   ├── styles.css           # Application styles (Bambu Lab green theme)
│   ├── app.js               # Frontend JavaScript
│   └── viewer3d.js          # 3D model viewer
├── uploads/
│   ├── files/               # Uploaded 3D model files (STL, OBJ, etc.)
│   └── images/              # Generated thumbnail images
├── .env                     # Environment variables
├── .env.example             # Example environment file
├── package.json             # Dependencies
└── README.md               # This file

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login
• GET /api/auth/me - Get current user (requires auth)

Models

• GET /api/models - List all models (supports search, tag, collection filters)
• GET /api/models/:id - Get single model
• POST /api/models - Upload new model (requires auth)
• PUT /api/models/:id - Update model metadata (requires auth)
• DELETE /api/models/:id - Delete model (requires auth)
• GET /api/models/:id/download - Download model file

Collections

• GET /api/collections - List all collections
• GET /api/collections/:id - Get collection with models
• POST /api/collections - Create collection (requires auth)
• PUT /api/collections/:id - Update collection (requires auth)
• DELETE /api/collections/:id - Delete collection (requires auth)

Tags

• GET /api/tags - List all tags
• GET /api/tags/:id/models - Get models by tag
• POST /api/tags - Create tag (requires auth)
• PUT /api/tags/:id - Update tag (requires auth)
• DELETE /api/tags/:id - Delete tag (requires auth)

Features in Detail

User Registration & Authentication

• Secure password hashing with bcrypt
• JWT-based authentication
• 7-day token expiration

Model Upload

• Drag and drop or browse to upload
• Automatic file validation
• Support for multiple 3D file formats
• 100MB file size limit (configurable)
• Rich metadata support

Search & Filtering

• Full-text search across model names, descriptions, and creators
• Filter by tags
• Filter by collections
• Real-time search with debouncing

Collections & Tags

• Create unlimited collections to organize models
• Add colorful tags for categorization
• View model counts for each collection and tag

Future Enhancements

• Advanced 3D model preview with Three.js STL/OBJ loader
• Thumbnail generation for models
• Batch upload support
• Export collections as ZIP
• Model versioning
• Print history tracking
• Filament usage calculator
• Public sharing and privacy controls
• ActivityPub federation support
• Advanced search with faceted filtering
• Model duplicate detection
• PostgreSQL support
• S3/Object storage support

Security Notes

• Always change the default JWT_SECRET and SESSION_SECRET in production
• Use HTTPS in production
• Consider adding rate limiting for API endpoints
• Implement file type validation on the server side
• Add virus scanning for uploaded files in production
• Use environment variables for sensitive data

Contributing

This is a powerful 3D model management system. Feel free to fork and modify for your needs!

License

MIT

Acknowledgments

• Built with love for makers and the 3D printing community

Support

For issues or questions, please check the code and documentation or modify as needed for your use case.

Quick Start Guide

1. Install dependencies: npm install
2. Start the server: npm start
3. Open browser to http://localhost:3000
4. Register a new account
5. Upload your first 3D model (STL, OBJ, or 3MF)
6. Click the 3D cube button to view models in interactive 3D!
7. Create collections and tags to organize your models
8. Enjoy managing your 3D printing files!