Initial commit: GSPro Remote MVP - Phase 1 complete

2025-11-13 15:38:58 -06:00 · 2025-11-13 15:38:58 -06:00 · 74ca4b38eb
commit 74ca4b38eb
50 changed files with 12818 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,212 @@
+# GSPro Remote
+
+A companion application for GSPro golf simulator that allows remote control from any device on your network.
+
+## 🎯 Overview
+
+GSPro Remote is a web-based remote control application for GSPro golf simulator running on Windows. Control GSPro from your tablet, phone, or another PC without needing a keyboard nearby.
+
+### Key Features
+
+- **Touch-Friendly Interface** - Optimized for tablets and phones
+- **All GSPro Shortcuts** - Full keyboard shortcut support via touch controls
+- **Live Map Streaming** - Real-time streaming of the GSPro mini-map
+- **mDNS Discovery** - Access via `gsproapp.local` on your network
+- **Persistent Settings** - Configuration saved between sessions
+- **Zero Cloud Dependencies** - Everything runs locally on your network
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Windows PC running GSPro
+- Python 3.11+
+- Node.js 20+
+- GSPro golf simulator
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/gspro-remote.git
+cd gspro-remote
+```
+
+2. Run the development setup:
+```powershell
+.\scripts\dev.ps1
+```
+
+This will:
+- Install all backend dependencies
+- Install all frontend dependencies
+- Start both development servers
+- Open the UI at http://localhost:5173
+
+### Access Points
+
+- **Frontend UI**: http://localhost:5173
+- **Backend API**: http://localhost:5005
+- **API Documentation**: http://localhost:5005/api/docs
+- **mDNS Access**: http://gsproapp.local:5005
+
+## 📁 Project Structure
+
+```
+gspro-remote/
+├── backend/                 # Python FastAPI backend
+│   ├── app/
+│   │   ├── api/            # API endpoints
+│   │   │   ├── actions.py  # Keyboard control
+│   │   │   ├── vision.py   # Screen streaming
+│   │   │   ├── config.py   # Configuration
+│   │   │   └── system.py   # System utilities
+│   │   ├── core/           # Core functionality
+│   │   │   ├── config.py   # Config management
+│   │   │   ├── input_ctrl.py # Windows input
+│   │   │   ├── screen.py   # Screen capture
+│   │   │   └── mdns.py     # mDNS service
+│   │   └── main.py         # FastAPI app
+│   └── pyproject.toml      # Python dependencies
+│
+├── frontend/               # React TypeScript frontend
+│   ├── src/
+│   │   ├── pages/         # Page components
+│   │   ├── components/    # UI components
+│   │   ├── api/          # API client
+│   │   ├── stores/       # State management
+│   │   └── App.tsx       # Main app
+│   └── package.json      # Node dependencies
+│
+├── scripts/              # Development scripts
+│   └── dev.ps1          # Windows dev script
+│
+└── PRD.md              # Product requirements
+```
+
+## 🎮 Features
+
+### Phase 1 (MVP) - Current
+- ✅ Directional pad for aim control
+- ✅ Club selection (up/down)
+- ✅ Mulligan button
+- ✅ Tee box navigation
+- ✅ Map panel with streaming
+- ✅ All GSPro keyboard shortcuts
+- ✅ WebSocket-based streaming
+- ✅ Configuration persistence
+- ✅ mDNS service discovery
+
+### Phase 2 (Planned)
+- ⏳ OCR-based auto-detection
+- ⏳ Visual marker tracking
+- ⏳ Background monitoring
+- ⏳ Advanced automation
+
+### Phase 3 (Future)
+- ⏳ Enhanced UI/UX
+- ⏳ Subscription features
+- ⏳ Extended documentation
+
+## 🛠️ Development
+
+### Backend Development
+
+```bash
+cd backend
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev]"
+uvicorn app.main:app --reload --host 0.0.0.0 --port 5005
+```
+
+### Frontend Development
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+### Running Tests
+
+Backend:
+```bash
+cd backend
+pytest
+```
+
+Frontend:
+```bash
+cd frontend
+npm test
+```
+
+## 📖 API Documentation
+
+The backend provides a comprehensive REST API with WebSocket support for streaming.
+
+### Key Endpoints
+
+- `POST /api/actions/key` - Send keyboard input to GSPro
+- `WS /api/vision/ws/stream` - WebSocket for map streaming
+- `GET /api/config` - Get current configuration
+- `GET /api/system/health` - Health check
+
+Full API documentation available at http://localhost:5005/api/docs when running.
+
+## 🔧 Configuration
+
+Configuration is stored at `%LOCALAPPDATA%\GSPro Remote\config.json`
+
+### Default Configuration
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 5005,
+    "mdns_enabled": true
+  },
+  "capture": {
+    "fps": 30,
+    "quality": 85,
+    "resolution": "720p"
+  },
+  "gspro": {
+    "window_title": "GSPro",
+    "auto_focus": true
+  }
+}
+```
+
+## 🐛 Troubleshooting
+
+### GSPro Window Not Found
+- Ensure GSPro is running
+- Check window title in configuration
+- Run backend as administrator if needed
+
+### Connection Issues
+- Verify both frontend and backend are running
+- Check Windows firewall settings
+- Ensure devices are on same network
+
+### Port Already in Use
+- Check if another instance is running
+- Change port in configuration
+- Use `netstat -an | findstr :5005` to check
+
+## 📝 License
+
+MIT License - See LICENSE file for details
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📞 Support
+
+For issues and questions:
+- Create an issue on GitHub
+- Check existing issues for solutions