# Development Guide

## Prerequisites

- Ruby 3.3+
- Docker

## Setup

```bash
# Clone repository
git clone https://github.com/ryankazokas/turbovault-app.git
cd turbovault

# Start services (PostgreSQL + Mailpit)
task docker:up

# Setup database
task db:setup

# Run development server
task dev
```

Visit http://localhost:3000

**Demo:** `demo@turbovault.com` / `password123`

## Commands

```bash
# Development
task dev              # Start Rails + CSS watcher
task server           # Rails only
task console          # Rails console

# Database
task db:migrate       # Run migrations
task db:rollback      # Rollback migration
task db:reset         # Reset database
task db:seed          # Load seed data

# Testing
task test             # Run tests
task test:system      # System tests

# Code Quality
task lint             # Check style
task lint:fix         # Auto-fix style
task typecheck        # Type checker
task security         # Security scan

# Type Checking
task tapioca:init     # First time only
task tapioca:all      # After bundle install
task typecheck:watch  # Watch mode

# Services
task docker:up        # Start services
task docker:down      # Stop services
task docker:logs      # View logs

# IGDB
task igdb:sync        # Manual sync
task igdb:status      # Check status
task igdb:clear       # Clear stuck jobs

# Cleanup
task clean            # Remove tmp/logs
```

## Project Structure

```
app/
├── controllers/      # Controllers
├── models/           # Models
├── views/            # ERB templates
├── javascript/       # Stimulus controllers
├── services/         # Service objects (IgdbService)
└── jobs/             # Background jobs (IgdbSyncJob)

config/
├── routes.rb         # Routes
├── database.yml      # Database config
├── queue.yml         # Solid Queue config
└── recurring.yml     # Recurring jobs (IGDB sync)

k8s/                  # Kubernetes manifests
docs/                 # Documentation
```

## Environment Variables

Copy `.env.example` to `.env`:

```bash
# Optional: IGDB API
IGDB_CLIENT_ID=your_client_id
IGDB_CLIENT_SECRET=your_client_secret
```

Get credentials: https://dev.twitch.tv

## Contributing

1. Fork repository
2. Create feature branch
3. Make changes
4. Run: `task test && task lint:fix && task typecheck`
5. Submit PR

## Troubleshooting

```bash
# Database issues
task docker:up && task db:reset

# Type errors
task tapioca:all && task typecheck

# Tests failing
task db:test:prepare && task test
```