Quest 100 Rails Development Guide

This skill provides guidance for working with the "My Academy Quest" Rails application - a quest management system with real-time updates using Turbo Streams.

Project Overview

Ruby on Rails 8.0.2 application for managing academic quests with:

Development Commands

Running Tests

1. **Full test suite**: `bundle exec rspec`

2. **Model tests only**: `bundle exec rspec spec/models`

3. **Request tests only**: `bundle exec rspec spec/requests`

4. **Routing tests only**: `bundle exec rspec spec/routing`

5. **Acceptance tests**: `bundle exec cucumber`

Code Quality & Linting

1. **Run linter**: `bundle exec rubocop`

2. **Auto-fix violations**: `bundle exec rubocop -a`

3. **Security analysis**: `bundle exec brakeman`

Database Operations

1. **Run migrations**: `bundle exec rails db:migrate`

2. **Setup from scratch**: `bundle exec rails db:setup`

3. **Reset database**: `bundle exec rails db:reset`

Asset Management

1. **Build Tailwind CSS**: `bundle exec rails tailwindcss:build`

2. **Watch and rebuild CSS**: `bundle exec rails tailwindcss:watch`

Starting Development Server

1. **Standard server**: `bundle exec rails server`

2. **With Procfile**: `bin/dev`

Architecture Guidelines

Models (`app/models/`)

**Quest Model** (`quest.rb`):

Controllers (`app/controllers/`)

**QuestsController** (`quests_controller.rb`):

**BragController** (`brag_controller.rb`):

Routing Conventions

Frontend Stack

1. **Turbo Streams**: Real-time updates without page refreshes for create, destroy, toggle operations

2. **Stimulus**: JavaScript framework for interactive behaviors

3. **Tailwind CSS**: Utility-first, mobile-first responsive design

4. **Importmap**: Module management (no bundler needed)

Database Schema

**quests table**:

Code Standards

Ruby Style

Rails Conventions

Testing Requirements

Implementation Steps

When adding new features:

1. **Start with tests**:

- Write RSpec model specs for validations and behavior

- Write request specs for controller actions

- Write routing specs if adding custom routes

- Write Cucumber scenarios for user flows

2. **Create database migration**:

- `bundle exec rails generate migration AddFeatureToModel`

- Run `bundle exec rails db:migrate`

3. **Implement model**:

- Add validations

- Add callbacks if needed (prefer `after_initialize` pattern)

- Keep models focused and single-responsibility

4. **Build controller**:

- Use strong parameters with `expect`

- Add Turbo Stream responses for dynamic updates

- Handle errors gracefully

5. **Create views**:

- Use Turbo Frame/Stream tags for real-time updates

- Style with Tailwind CSS utility classes

- Ensure mobile-responsive design

6. **Run quality checks**:

- `bundle exec rspec` - All tests pass

- `bundle exec rubocop` - No violations

- `bundle exec brakeman` - No security issues

- `bundle exec cucumber` - Acceptance tests pass

Key Patterns

Turbo Stream Updates

```ruby

Controller pattern

respond_to do |format|

format.turbo_stream

format.html { redirect_to root_path }

end

```

Status Toggle Pattern

Mobile-First Design

Constraints

Examples

Adding a New Quest Property

1. Generate migration: `bundle exec rails generate migration AddDescriptionToQuests description:text`

2. Run migration: `bundle exec rails db:migrate`

3. Add validation in `app/models/quest.rb`: `validates :description, length: { maximum: 500 }`

4. Update strong params in controller: `params.expect(quest: [:name, :description])`

5. Update views to include description field

6. Write RSpec tests for validation

7. Update Cucumber scenarios if user-facing

8. Run full test suite and code quality checks

Creating a New Resource

1. Generate scaffold: `bundle exec rails generate scaffold Category name:string`

2. Review and customize generated files

3. Add associations to existing models if needed

4. Write comprehensive tests (model, request, routing specs)

5. Add Turbo Stream responses to controller actions

6. Style views with Tailwind CSS

7. Run full test suite

8. Run RuboCop and fix any violations