https://github.com/lordbuffcloud/bowlytics-app
Bowlytics is an advanced bowling analytics platform that helps bowlers track their performance, get AI-powered coaching advice, and improve their game through data-driven insights.
https://github.com/lordbuffcloud/bowlytics-app
Last synced: 5 days ago
JSON representation
Bowlytics is an advanced bowling analytics platform that helps bowlers track their performance, get AI-powered coaching advice, and improve their game through data-driven insights.
- Host: GitHub
- URL: https://github.com/lordbuffcloud/bowlytics-app
- Owner: lordbuffcloud
- License: mit
- Created: 2025-01-17T10:48:24.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-12-13T00:57:33.000Z (6 months ago)
- Last Synced: 2025-12-14T15:51:14.022Z (6 months ago)
- Language: HTML
- Size: 77.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Bowlytics - Bowling Analytics Platform
Bowlytics is an advanced bowling analytics platform that helps bowlers track their performance, get AI-powered coaching advice, and improve their game through data-driven insights.
## Features
### Core Features
- **Shot Tracking**: Record detailed information about each bowling shot
- Ball selection and characteristics
- Lane positioning and targeting
- Pin impact and results
- Oil pattern and lane conditions
- **AI Coach Bernie**: Get real-time coaching advice powered by GPT-4o
- Shot-by-shot analysis with ML-enhanced insights
- Pattern recognition and lane transition detection
- Targeted adjustments based on historical performance
- Performance insights with confidence scoring
### Advanced Machine Learning Features
- **Enhanced ML Insights**:
- Advanced strike probability prediction using logistic regression
- Optimal positioning recommendations (board, arrow, impact point)
- Lane transition analysis with trend detection
- Ball recommendation engine with success rate analysis
- Speed optimization with confidence intervals
- Pattern-specific performance analysis
- Burn level impact assessment
- **Predictive Analytics**:
- Next shot recommendations based on current conditions
- Real-time strike probability predictions
- Optimal setup suggestions before each shot
- Lane condition predictions
### Advanced Analytics Dashboard
- **Performance Dashboard**:
- Strike and spare percentages with trends
- Daily performance trends with visualizations
- Ball performance comparison
- Pattern-specific statistics
- Hot/cold streak tracking
- Optimal conditions identification
- **Advanced Analytics View**:
- Interactive performance charts (Chart.js)
- Ball-by-ball performance breakdown
- Pattern performance analysis
- Optimal conditions display
- Historical trend visualization
### Spare Analysis
- **Intelligent Spare System**:
- Spare conversion probability prediction
- Historical spare attempt analysis
- Recommended approach for each pin configuration
- Success rate tracking by spare type
## Project Structure
```
bowlytics_api/
├── app.py # Main Flask application
├── db.py # Database configuration
├── models.py # SQLAlchemy models
├── ml_insights.py # Machine learning analysis
├── fix_data.py # Data cleanup utilities
├── frontend/ # Frontend files
│ ├── index.html # Main web interface
│ └── server.py # Frontend server
├── data/ # Data storage
│ ├── bowling_data.csv # Shot history
│ └── spare_stats.csv # Spare attempt stats
└── requirements.txt # Python dependencies
```
## File Descriptions
- `app.py`: Core backend application with API endpoints for shot tracking, analysis, and AI coaching
- `db.py`: Database configuration and connection management
- `models.py`: SQLAlchemy models defining data structures for shots and spare attempts
- `ml_insights.py`: Machine learning algorithms for performance analysis and predictions
- `fix_data.py`: Utility script for cleaning and maintaining data integrity
- `frontend/index.html`: Main web interface with interactive dashboard and data entry forms
- `frontend/server.py`: Simple Flask server for serving the frontend
## Setup Instructions
1. **Clone the Repository**
```bash
git clone https://github.com/yourusername/bowlytics.git
cd bowlytics
```
2. **Create Virtual Environment**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install Dependencies**
```bash
pip install -r requirements.txt
```
4. **Environment Setup**
Create a `.env` file in the root directory:
```
OPENAI_API_KEY=your_api_key_here
DATABASE_URL=sqlite:///bowlytics.db
```
5. **Initialize Database**
```bash
python -c "from db import Base, engine; Base.metadata.create_all(bind=engine)"
```
6. **Start the Backend**
```bash
python app.py
```
7. **Start the Frontend**
```bash
cd frontend
python server.py
```
8. **Access the Application**
Open your browser and navigate to:
- Frontend: http://localhost:5111
- API: http://localhost:8765
## API Endpoints
### Core Endpoints
- `GET /bowling-shots`: Retrieve shot history
- `POST /bowling-shot`: Record a new shot
- `GET /ai-coach`: Get AI coaching advice (enhanced with ML insights)
- `GET /dashboard-stats`: Get performance statistics with ML insights
- `GET /last-shot`: Get the most recent shot data
### Advanced Analytics Endpoints
- `GET /advanced-analytics`: Get comprehensive analytics including:
- Daily performance trends
- Ball performance breakdown
- Pattern performance analysis
- Burn level impact
- Hot/cold streaks
- Optimal conditions
- `POST /predict-next-shot`: Get ML-powered next shot recommendation
- Requires current shot conditions in request body
- Returns optimal ball, position, speed, and strike probability
### Spare Endpoints
- `POST /spare-attempt`: Record a spare attempt
- `POST /spare-analysis`: Analyze spare conversion probability and get recommendations
## Dependencies
- Flask: Web framework
- SQLAlchemy: Database ORM
- Pandas: Data analysis
- OpenAI: AI coaching (GPT-4)
- scikit-learn: Machine learning insights
- python-dotenv: Environment management
## Development
1. **Database Migrations**
- The application uses SQLite by default
- Models are defined in `models.py`
- Run `fix_data.py` to clean data if needed
2. **Adding Features**
- Backend: Add routes to `app.py`
- Frontend: Modify `index.html`
- ML: Enhance `ml_insights.py`
3. **Testing**
```bash
python test_endpoint.py
```
## Production Deployment
1. **Server Requirements**
- Python 3.8+
- OpenAI API access
- Adequate storage for CSV files
2. **Deployment Steps**
```bash
# Install production dependencies
pip install gunicorn
# Start with gunicorn
gunicorn -w 4 -b 0.0.0.0:8765 app:app
```
3. **Using the Service File**
```bash
# Copy service file
sudo cp bowlytics.service /etc/systemd/system/
# Start service
sudo systemctl start bowlytics
sudo systemctl enable bowlytics
```
## Security Notes
1. **API Key Protection**
- Store OpenAI API key in `.env`
- Never commit API keys to version control
2. **Data Privacy**
- Shot data is stored locally
- No personal information is collected
- Optional: Implement user authentication
## Troubleshooting
1. **Data Issues**
- Run `fix_data.py` to repair CSV files
- Check file permissions in data directory
- Verify CSV column headers
2. **API Errors**
- Verify OpenAI API key
- Check network connectivity
- Review app.log for details
3. **Frontend Issues**
- Clear browser cache
- Check browser console
- Verify API endpoint URLs
## Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- OpenAI for GPT-4 integration
- scikit-learn for ML capabilities
- Flask community for web framework
- All contributors and users
## Contact
For support or queries, please open an issue on GitHub.