turbovault-app/README.md

# 🎮 TurboVault

> Your personal video game collection tracker and manager

[![Rails 8.1](https://img.shields.io/badge/Rails-8.1-red.svg)](https://rubyonrails.org/)
![CI](https://github.com/YOUR_USERNAME/turbovault/workflows/CI/badge.svg)
[![RuboCop](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
[![Sorbet](https://img.shields.io/badge/types-sorbet-blue.svg)](https://sorbet.org)
[![Ruby 3.3](https://img.shields.io/badge/Ruby-3.3-red.svg)](https://www.ruby-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TurboVault is a modern, self-hosted web application for tracking and organizing your video game collection. Built with Rails 8 and Hotwire, it offers a fast, responsive experience for managing physical and digital games across all platforms.

## ✨ Features

- 📚 **Track Physical & Digital Games** - Manage both formats with detailed metadata
- 🎮 **IGDB Integration** - Automatic game matching with cover art and metadata
- 📊 **Collection Statistics** - Track spending, completion rates, and platform distribution
- 🗂️ **Collections** - Organize games into custom collections
- 🔍 **Smart Search** - Find games quickly with advanced filtering
- 📥 **CSV Import** - Bulk import your existing collection
- 🎨 **5 Beautiful Themes** - Light, Dark, Midnight, Retro, and Ocean
- 🔐 **RESTful API** - Programmatic access to your collection
- 📍 **Location Tracking** - Remember where your physical games are stored
- ⭐ **Ratings & Status** - Track completion status and personal ratings
- 👥 **Public Profiles** - Optionally share your collection with others

## 🚀 Quick Start

### Prerequisites

- Ruby 3.3+
- PostgreSQL 15+
- Node.js 18+ (for asset compilation)
- Docker (optional, for containerized development)

### Local Development

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/turbovault.git
   cd turbovault
   ```

2. **Install dependencies**
   ```bash
   bundle install
   ```

3. **Set up environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. **Start Docker services**
   ```bash
   docker-compose up -d
   ```

5. **Set up the database**
   ```bash
   rails db:prepare
   ```

6. **Start the development server**
   ```bash
   task dev
   # or: bin/dev
   ```

7. **Visit the app**
   - App: http://localhost:3000
   - Mailpit (email testing): http://localhost:8025

### Demo Account

A demo account is automatically created in development:
- **Email:** demo@turbovault.com
- **Password:** password123

## 🐳 Docker Deployment

TurboVault includes Docker and Kubernetes manifests for easy deployment.

### Kubernetes (Recommended for Production)

TurboVault is designed for Kubernetes with automated GitHub Actions CI/CD.

**📖 Documentation:**
- ⭐ [Quick Start Guide](docs/QUICK_START.md) - Deploy in minutes
- [Deployment Guide](docs/DEPLOYMENT.md) - Complete reference
- [Kubernetes README](k8s/README.md) - K8s details

**🚀 Quick Deploy:**
```bash
# 1. Push to GitHub
git push origin main

# 2. Tag a release (triggers automatic build)
git tag v1.0.0 && git push origin v1.0.0

# 3. Configure Kubernetes secrets & manifests
cp k8s/secrets.yaml.example k8s/secrets.yaml
# Edit secrets.yaml, deployment.yaml, configmap.yaml

# 4. Deploy
./scripts/deploy-k8s.sh
```

See [Quick Start Guide](docs/QUICK_START.md) for detailed steps.

### Docker Compose (Development/Testing)

```bash
docker-compose -f docker-compose.prod.yml up -d
```

## 🔧 Configuration

### IGDB Integration (Optional)

To enable automatic game metadata matching:

1. Create a Twitch developer account at https://dev.twitch.tv
2. Register an application to get your Client ID and Secret
3. Add to `.env`:
   ```bash
   IGDB_CLIENT_ID=your_client_id
   IGDB_CLIENT_SECRET=your_client_secret
   ```

IGDB sync is enabled by default for all users and runs every 30 minutes.

## 📚 Documentation

**All documentation is in the [`docs/`](docs/) folder.**

**Quick Links:**
- ⭐ [Quick Start](docs/QUICK_START.md) - Deploy in minutes
- 🚀 [Deployment Guide](docs/DEPLOYMENT.md) - Complete reference
- 💻 [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Local development
- 📖 [API Documentation](docs/API_DOCUMENTATION.md) - RESTful API
- 🎮 [IGDB Integration](docs/IGDB_INTEGRATION.md) - Game metadata
- 🎨 [Themes](docs/THEMES.md) - Customization
- 🔷 [Sorbet Types](docs/SORBET.md) - Type checking guide
- 🎯 [Demo Account](docs/DEMO_ACCOUNT.md) - Try it out

[**See all documentation →**](docs/README.md)

## 🛠️ Tech Stack

- **Framework:** Ruby on Rails 8.1 with Sorbet type checking
- **Frontend:** Hotwire (Turbo + Stimulus)
- **Styling:** Tailwind CSS
- **Database:** PostgreSQL with Row Level Security
- **Background Jobs:** Solid Queue
- **Deployment:** Docker, Kubernetes
- **APIs:** IGDB (game metadata)

## 🤖 Continuous Integration

TurboVault includes GitHub Actions workflows:

- **CI Pipeline** - Runs tests, linting, and security scans on every push
- **Build & Push** - Automatically builds Docker images and pushes to GitHub Container Registry

### Setup GitHub Actions

**No setup required!** The default workflow uses GitHub Container Registry (ghcr.io), which works out of the box with no secrets needed.

Just push a tag:
```bash
git tag v1.0.0
git push origin v1.0.0
```

Your image will be at: `ghcr.io/your-username/turbovault:v1.0.0`

**Want to use a different registry?** See [.github/SECRETS_SETUP.md](.github/SECRETS_SETUP.md) for examples (Docker Hub, private registry, etc.)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

All PRs will automatically run CI tests.

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Game data provided by [IGDB](https://www.igdb.com/)
- Built with [Ruby on Rails](https://rubyonrails.org/)
- UI powered by [Tailwind CSS](https://tailwindcss.com/)

## 📧 Support

- 📖 [Documentation](docs/)
- 🐛 [Issue Tracker](https://github.com/yourusername/turbovault/issues)
- 💬 [Discussions](https://github.com/yourusername/turbovault/discussions)

---

Made with ❤️ for gamers and collectors