🏰 under_world - Life Gamification MMORPG Backend

A comprehensive Ruby on Rails API backend for the Life Gamifier MMORPG system, transforming daily life into an engaging RPG experience.

🎮 Overview

under_world is the Rails-based backend API that powers the Life Gamifier MMORPG system. It provides a comprehensive set of APIs for user management, quest tracking, social features, and real-time communication. The frontend OverWorld Unity app connects to this backend to create an immersive AR life gamification experience.

✨ Core Features

• 🔐 Authentication System - JWT-based auth with Google OAuth2 integration
• 🎯 Quest Management - Dynamic quest creation, tracking, and completion
• 👥 Social Features - Guilds, parties, friendships, and mentorship
• 📊 Wellbeing Tracking - HP, mood, focus, energy monitoring with daily resets
• 🎨 Avatar System - Customizable user avatars with stats and equipment
• 💬 Real-time Chat - WebSocket-based messaging via Action Cable
• 🏆 Skills System - Skill progression, combinations, and mastery tracking
• 🤖 AI Integration - OpenAI-powered character interactions and adventures
• 🌍 Location Services - Google Places integration for real-world landmarks
• 📈 Analytics & Insights - User behavior tracking and gamification metrics

🏗️ Tech Stack

• Framework: Ruby on Rails 8.0.2 (API-only mode)
• Database: PostgreSQL 15+
• Cache/Queue: Redis 7+ with Solid Cache/Queue
• Background Jobs: Sidekiq
• Authentication: Devise + JWT
• Authorization: Pundit
• Real-time: Action Cable (WebSockets)
• AI: OpenAI GPT integration
• Deployment: Docker + Kamal
• Testing: RSpec with Factory Bot

📁 Project Structure

under_world/
├── 📁 app/
│   ├── controllers/api/v1/    # API endpoints
│   ├── models/               # Data models
│   ├── policies/            # Authorization rules
│   ├── serializers/         # JSON API serialization
│   ├── services/            # Business logic services
│   └── jobs/                # Background jobs
├── 📁 config/               # Configuration
├── 📁 db/                   # Database migrations & seeds
├── 📁 spec/                 # Tests (RSpec)
└── 📁 lib/tasks/            # Custom Rake tasks

🚀 Quick Start

Prerequisites

• Ruby 3.2+
• PostgreSQL 15+
• Redis 7+
• Node.js 18+ (for some dependencies)

1. Clone and Setup

git clone https://github.com/yourusername/under_world.git
cd under_world
bundle install

2. Environment Configuration

Create .env file:

# Database
DATABASE_URL=postgresql://localhost/under_world_development

# JWT Authentication
DEVISE_JWT_SECRET_KEY=your_super_secret_jwt_key_here

# Google OAuth2
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# External Services
OPENAI_API_KEY=your_openai_api_key
GOOGLE_PLACES_API_KEY=your_google_places_api_key

# Redis
REDIS_URL=redis://localhost:6379/0

# CORS (for frontend)
CORS_ALLOWED_ORIGINS=http://localhost:3001,exp://192.168.1.117:19000

3. Database Setup

rails db:create
rails db:migrate
rails db:seed

4. Start Services

# Start Redis
redis-server

# Start Sidekiq (background jobs)
bundle exec sidekiq

# Start Rails server
rails server -p 3000

📚 API Endpoints

Authentication

POST /api/v1/auth/sign_in          # User login
POST /api/v1/auth/sign_up          # User registration
GET  /api/v1/users/me              # Current user profile

Quest Management

GET    /api/v1/quests              # List user quests
POST   /api/v1/quests              # Create new quest
POST   /api/v1/quests/:id/complete # Complete quest

Guild System

GET  /api/v1/guilds                # List all guilds
POST /api/v1/guilds/:id/join       # Join guild
POST /api/v1/guilds/:id/leave      # Leave guild

Skills System

GET  /api/v1/skills                # List all skills
GET  /api/v1/user_skills           # User's skills
POST /api/v1/user_skills/fuse      # Fuse skills

Real-time Features

// WebSocket connection via Action Cable
const cable = ActionCable.createConsumer('ws://localhost:3000/cable');

🎯 Core Models

User Model

• Authentication with Devise + JWT
• Wellbeing tracking (HP, mood, focus, energy)
• Social connections (guilds, parties, friends)
• Skills progression system

Quest Model

• Synchronous/Asynchronous modes
• Manual/Auto completion types
• XP and coin rewards
• Label categorization

Guild Model

• Member management
• Collaborative quests
• Guild-specific features

Skills System

• Skill categories and progression
• Experience points and mastery
• Skill fusion mechanics
• User skill selections

🛠️ Services & Business Logic

AI Character Service

class AiCharacterService
  def generate_adventure(context)
    # Generate AI-powered adventures
  end
  
  def chat_response(message)
    # AI character interactions
  end
end

Weather Service

• Real-time weather data integration
• Weather-based quest modifiers
• Environmental effects

Google Places Service

• Location-based features
• Landmark integration
• Real-world quest locations

🧪 Testing

# Run all tests
bundle exec rspec

# Run specific test types
bundle exec rspec spec/models/
bundle exec rspec spec/requests/

# Run with coverage
COVERAGE=true bundle exec rspec

🚀 Deployment

Docker

FROM ruby:3.2-alpine
WORKDIR /app
COPY Gemfile* ./
RUN bundle install
COPY . .
EXPOSE 3000
CMD ["rails", "server", "-b", "0.0.0.0"]

Kamal Deployment

kamal setup    # First-time setup
kamal deploy   # Deploy updates

🔐 Security Features

• JWT authentication with automatic expiration
• Google OAuth2 integration
• Pundit authorization policies
• CORS configuration
• Input validation and sanitization
• Rate limiting
• SQL injection prevention

📈 Performance Features

• Database query optimization
• Redis caching strategy
• Background job processing
• Efficient API serialization
• Connection pooling

🐛 Troubleshooting

Common Issues

Database Connection

pg_isready -d under_world_development
rails db:reset  # If needed

Redis Connection

redis-cli ping
redis-cli flushall  # Clear cache if needed

Background Jobs

bundle exec sidekiq  # Start job processor

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Code Standards

• Follow Ruby/Rails conventions
• Write comprehensive tests
• Add documentation for new features
• Use meaningful commit messages

📄 License

This project is licensed under the MIT License.

🔗 Related Projects

• OverWorld - Unity AR frontend
• MMORPG Tools - Development utilities and MCP servers

📞 Support

• Issues: GitHub Issues
• API Documentation: Available when server is running
• Frontend Integration: See OverWorld repository

---

🏰 Ready to power life gamification? Clone, configure, and start building today!

Made with ❤️ for the life gamification community