Skip to content

README.md

Latest commit

 

History

History
262 lines (197 loc) · 8.2 KB

README.md

File metadata and controls

262 lines (197 loc) · 8.2 KB

LaxCheck - Open Source Lacrosse Head Identification System

License: MIT Node.js Version TypeScript

LaxCheck is a comprehensive, open-source lacrosse head identification and valuation platform that combines machine learning with AI-powered market analysis to help collectors identify equipment and find the highest market prices for their lacrosse heads.

🚀 Features

Core Identification System

  • Advanced ML Pipeline: Custom TensorFlow.js model with 14+ lacrosse head classes
  • OpenCV Preprocessing: Image enhancement, background removal, and edge detection
  • AI-Powered Analysis: OpenAI GPT-4 Vision integration for comprehensive equipment analysis
  • PDF Report Generation: Detailed analysis reports with technical specifications and market data

Market Intelligence

  • Real-time Valuation: Live market pricing from multiple platforms
  • Highest Price Finder: Identifies best selling platforms and optimal pricing
  • Market Trends: Real-time pricing data and market movement tracking
  • Demand Analysis: Platform-specific demand and pricing optimization

User Experience

  • Drag & Drop Upload: Support for up to 3 photos per analysis
  • Mobile Optimized: Responsive design for desktop and mobile use
  • Real-time Processing: Live progress tracking during analysis
  • Performance Dashboard: System analytics and identification metrics

🛠️ Technology Stack

Frontend

  • React 18 with TypeScript
  • Vite for development and building
  • Tailwind CSS for styling
  • Radix UI for accessible components
  • TanStack Query for state management
  • Wouter for routing

Backend

  • Node.js with Express
  • TypeScript for type safety
  • PostgreSQL with Drizzle ORM
  • TensorFlow.js Node for ML inference
  • OpenAI SDK for AI analysis
  • Sharp for image processing

Machine Learning

  • Custom TensorFlow Model: Trained on 1000+ lacrosse head images
  • Google Teachable Machine: Training pipeline for model updates
  • Image Preprocessing: Advanced OpenCV-style processing pipeline
  • Confidence Thresholding: Smart fallback to AI analysis

🏗️ Project Structure

laxcheck/
├── client/                 # React frontend
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Route components
│   │   ├── lib/           # Utilities and configuration
│   │   └── hooks/         # Custom React hooks
├── server/                # Node.js backend
│   ├── routes.ts          # API endpoints
│   ├── enhanced_ml_identifier.ts  # ML processing pipeline
│   ├── openai.ts          # AI analysis service
│   ├── storage.ts         # Database operations
│   └── db.ts              # Database connection
├── shared/                # Shared TypeScript types
│   └── schema.ts          # Database schema and types
├── model/                 # ML model files
│   ├── model.json         # TensorFlow.js model
│   ├── weights.bin        # Model weights
│   └── metadata.json      # Class labels and metadata
├── electron/              # Desktop app wrapper
└── uploads/              # Image upload storage

🚀 Quick Start

Prerequisites

  • Node.js 20+
  • PostgreSQL database
  • OpenAI API key (optional, for enhanced analysis)

Installation

  1. Clone the repository
git clone https://github.com/yourusername/laxcheck.git
cd laxcheck
  1. Install dependencies
npm install
  1. Set up environment variables
cp .env.example .env
# Edit .env with your database URL and API keys
  1. Initialize database
npm run db:push
  1. Start development server
npm run dev

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

Desktop Application

Build and run the desktop version:

# Development
npm run electron:dev

# Build for production
npm run electron:build

🔧 Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://user:password@host:port/database

# AI Services (Optional)
OPENAI_API_KEY=your_openai_api_key

# Development
NODE_ENV=development
SESSION_SECRET=your_session_secret

ML Model

The system includes a pre-trained model with these classes:

  • Warrior Blade, Jett, Evolution series
  • Brine Edge, Cyber, Vapor series
  • STX Excalibur, SAM II
  • Nike Blur, Reebok 6K
  • Vintage and rare collector pieces
  • Unknown (fallback class)

To train a custom model:

  1. Collect 15+ photos per lacrosse head model
  2. Use Google Teachable Machine
  3. Export as TensorFlow.js
  4. Replace files in /model/ directory

📱 Deployment

Web Deployment (Replit)

  1. Deploy to Replit

    • Import from GitHub repository
    • Set environment variables in Secrets
    • Deploy using Replit's deployment system

  2. Custom Domain Setup

    • Configure custom domain in Replit
    • Update REPLIT_DOMAINS environment variable

Desktop Distribution

# Build for all platforms
npm run electron:build

# Platform-specific builds
npm run electron:build:win
npm run electron:build:mac
npm run electron:build:linux

Builds are output to /dist/ directory.

🤝 Contributing

We welcome contributions from the lacrosse community! Here's how to help:

Areas for Contribution

  1. ML Model Training: Add photos of rare/vintage heads
  2. Market Data: Contribute pricing information and sales data
  3. Feature Development: Enhance identification algorithms
  4. Documentation: Improve setup guides and tutorials
  5. Testing: Report bugs and edge cases

Development Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests if applicable
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Code Style

  • Use TypeScript for all new code
  • Follow existing naming conventions
  • Add JSDoc comments for new functions
  • Ensure responsive design for UI changes

📊 Performance

  • Model Accuracy: 87-92% on validation set
  • Processing Time: 2-8 seconds per analysis
  • Supported Formats: JPEG, PNG, WebP
  • Max File Size: 10MB per image
  • Concurrent Users: Optimized for 100+ simultaneous analyses

🛡️ Privacy & Security

  • Data Privacy: Images are processed locally, not stored permanently
  • No User Tracking: Anonymous usage for performance metrics only
  • Secure API Keys: Environment-based configuration
  • Open Source: Full transparency in processing methods

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏆 Community Impact

LaxCheck was created as a community gift to help collectors maximize the value of their lacrosse equipment. By making this system open source, we enable:

  • Maximum Value: Find the highest prices across all major marketplaces
  • Market Intelligence: Real-time pricing data and platform optimization
  • Educational Value: Learn about lacrosse equipment history and market trends
  • Community Building: Collaborative improvement of pricing accuracy

🙏 Acknowledgments

  • Google Teachable Machine for accessible ML training
  • OpenAI for advanced image analysis capabilities
  • The lacrosse collecting community for photos and market data
  • Contributors who help improve the system

📞 Support

Built with ❤️ for the lacrosse community

LaxCheck is dedicated to preserving lacrosse equipment history and maximizing collector value through open-source market intelligence and community collaboration.