turbovault-app/docs/DEVELOPMENT_GUIDE.md

Development Guide

Prerequisites

• Ruby 3.3+
• Docker

Setup

# 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

# 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:

# 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

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

# Type errors
task tapioca:all && task typecheck

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