Backend API server for Otter Drift, a Flutter/Flame mobile game where players navigate as an otter to avoid logs, collect lilies and hearts, and compete for high scores.

Otter Drift API is a Rails 8 JSON API that handles player authentication, game sessions, achievements, and leaderboards. Built with JWT authentication and fully documented with Swagger/OpenAPI via rswag.

• Ruby: 3.4.7
• Rails: 8.1.1 (API mode)
• Database: PostgreSQL
• Authentication: Devise + JWT (devise-jwt)
• Testing: RSpec + FactoryBot + Faker + Shoulda Matchers
• API Documentation: rswag (Swagger/OpenAPI)
• Web Server: Puma

• Ruby 3.4.7
• PostgreSQL
• Bundler

git clone <repository-url>
cd otter_drift_api

bundle install

Configure your PostgreSQL connection via environment variables or accept the defaults:

# Optional: Set database connection parameters
export PGHOST=localhost
export PGPORT=5432
export PGUSER=postgres
export PGPASSWORD=your_password

Create and setup databases:

# Create all databases (primary, cache, queue, cable)
bundle exec rails db:create

# Run migrations for all databases
bundle exec rails db:migrate

# Seed the database (optional)
bundle exec rails db:seed

For local development with Flutter mobile app, bind to 0.0.0.0 to allow connections from the mobile device:

rails server -b 0.0.0.0

The API will be available at http://0.0.0.0:3000

For local development only (desktop browser/Postman):

rails server

Interactive API documentation is available via Swagger UI once the server is running:

http://localhost:3000/api-docs

The API documentation is generated from RSpec request specs using rswag:

# Generate swagger.json from specs
RAILS_ENV=test bundle exec rake rswag:specs:swaggerize

# Or run specs and generate docs in one command
bundle exec rspec

This project uses RSpec for testing with the following tools:

• RSpec: Test framework
• FactoryBot: Test data factories
• Faker: Realistic fake data generation
• Shoulda Matchers: Clean one-liner tests for common Rails functionality
• rswag-specs: API documentation testing

bundle exec rspec

bundle exec rspec spec/models/player_spec.rb
bundle exec rspec spec/requests/api/v1/game_sessions_spec.rb

COVERAGE=true bundle exec rspec

POST /players

POST /players/sign_in

DELETE /players/sign_out

POST /api/v1/auth/login

GET    /api/v1/players/profile
PATCH  /api/v1/players/profile
GET    /api/v1/players/stats

POST   /api/v1/game_sessions
GET    /api/v1/game_sessions

GET    /api/v1/achievements
GET    /api/v1/players/:username/achievements

GET    /api/v1/players/:username/game-history

Retrieves complete game history for a player, including:

• All completed game sessions ordered by most recent
• Game statistics (lilies collected, obstacles avoided, hearts collected, max speed)
• High scores for each game
• Achievements earned during each game
• Pagination support with limit and offset query parameters

Query Parameters:

• limit: Number of games to return (default: 20, max: 100)
• offset: Offset for pagination (default: 0)

Example:

curl http://localhost:3000/api/v1/players/testplayer/game-history?limit=10&offset=0

GET    /api/v1/leaderboard

The application uses Rails 8's multi-database configuration:

• Primary: Main application data (players, game sessions, achievements, etc.)
• Cache: Solid Cache storage
• Queue: Solid Queue job processing
• Cable: Solid Cable for Action Cable

• Player: User accounts with Devise authentication
• PlayerProfile: Extended player information
• GameSession: Individual game play sessions
• HighScore: Player high scores
• Achievement: Available achievements
• EarnedAchievement: Player-earned achievements
• JwtDenylist: Revoked JWT tokens

# Run RuboCop linter
bundle exec rubocop

# Auto-fix offenses
bundle exec rubocop -a

# Run Brakeman security scanner
bundle exec brakeman

This project uses Bullet to detect N+1 queries and other performance issues.

In Development:

• Bullet is enabled and will log warnings to the console and Rails logger
• Check log/bullet.log for detailed reports
• Warnings appear in the terminal when N+1 queries are detected

In Tests:

• Bullet is configured to raise errors if N+1 queries are detected
• Tests will fail if performance issues are introduced
• This ensures optimal database queries are maintained

Common Bullet Notifications:

• N+1 Query: Use eager loading (.includes())
• Unused Eager Loading: Remove unnecessary .includes()
• Counter Cache: Consider adding counter cache columns for frequently counted associations

bundle exec rails console

Deploy using your preferred method (Heroku, DigitalOcean, AWS, etc.). Ensure environment variables are properly configured in your deployment environment.

Key environment variables:

# Database
PGHOST=localhost
PGPORT=5432
PGUSER=postgres
PGPASSWORD=your_password
PGDATABASE=otter_drift_api_development

# Rails
RAILS_ENV=development
RAILS_MAX_THREADS=5

# JWT Secret (auto-generated by devise-jwt)
DEVISE_JWT_SECRET_KEY=your_secret_key

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

This project is not open source. All rights are reserved by the author.

For issues and questions, please open an issue in the repository.