Propel Rails

A modular Ruby framework meta gem that orchestrates the installation of Propel components for building modern web applications with comprehensive dynamic filtering capabilities.

🎉 NEW in v0.3.3: Dynamic Filtering System

Propel Rails now orchestrates a complete automatic URL query string filtering and scoping system across all components. This provides powerful, database-agnostic filtering with zero configuration required.

Quick Filtering Examples

# String filtering
GET /api/v1/meetings?title_contains=Project&status_in=active,pending

# Numeric filtering  
GET /api/v1/meetings?max_participants_gte=50&max_participants_lte=200

# Boolean filtering
GET /api/v1/meetings?recording_enabled_eq=true&ai_research_enabled_eq=false

# DateTime filtering
GET /api/v1/meetings?start_time_after=2024-01-01T00:00:00Z&start_time_before=2024-12-31T23:59:59Z

# Range filtering
GET /api/v1/meetings?max_participants_range=150,350

# Combined filtering with sorting and pagination
GET /api/v1/meetings?title_contains=Project&max_participants_gte=50&order_by=start_time&page=1&limit=20

Supported Filter Operators

Data Type	Operators	Examples
String	`_eq`, `_contains`, `_starts_with`, `_ends_with`, `_in`	`name_eq=Acme`, `title_contains=Project`
Numeric	`_eq`, `_gt`, `_lt`, `_gte`, `_lte`, `_range`, `_in`	`max_participants_gte=50`, `price_range=100,500`
Boolean	`_eq` (supports `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`)	`recording_enabled_eq=true`
DateTime	`_before`, `_after`, `_year`, `_month`, `_day`, `_date`	`start_time_after=2024-01-01`, `created_at_year=2024`
Date	Same as DateTime	`event_date_after=2024-01-01`
Time	Same as DateTime	`start_time_hour=14`

Automatic Features

Zero Configuration: Filtering works automatically for all generated resources
Database Agnostic: Works with SQLite, PostgreSQL, and MySQL
Security Built-in: SQL injection protection and input validation
Multi-tenancy Ready: Automatic organization scoping
Performance Optimized: Efficient queries with proper indexing support

Overview

Propel Rails is a meta gem that provides unified installation and configuration for the Propel framework ecosystem. It coordinates the setup of multiple self-extracting Propel gems to create a complete development environment.

Installation

Add this line to your application's Gemfile:

gem 'propel_rails', path: 'propel_rails'

And then execute:

bundle install

Usage

Propel Rails provides an orchestrator that manages the installation of individual Propel components. You can install all components together or pick specific ones for your needs.

Full Framework Installation

# Add all Propel gems to your Gemfile
gem 'propel_rails', path: 'propel_rails'
gem 'propel_api', path: 'propel_api'
gem 'propel_auth', path: 'propel_auth'
gem 'propel_facets', path: 'propel_facets'

bundle install

# Install all components with orchestration
rails generate propel:install

Selective Component Installation

# Install only API components
rails generate propel:install --api-only

# Install only authentication
rails generate propel:install --auth-only

# Install only facets system
rails generate propel:install --facets-only

# Install API with Graphiti instead of PropelFacets
rails generate propel:install --graphiti

# Custom API configuration
rails generate propel:install --api-version=v2 --api-namespace=admin_api

Available Components

When you install propel_rails, it can orchestrate the installation of:

propel_api - Complete API resource generation with dual serialization support
propel_auth - JWT-based authentication with multi-tenancy
propel_facets - Flexible JSON representations for models
graphiti - JSON:API serialization (alternative to PropelFacets)

Framework Configuration

Propel::Rails.configure do |config|
  config.environment = 'production'  # or 'development', 'test'
  config.logger = Rails.logger
  config.root_path = Rails.root
end

Environment Detection

if Propel::Rails.configuration.development?
  puts "Running in development mode"
end

if Propel::Rails.configuration.production?
  puts "Running in production mode"
end

Component Details

PropelApi Integration

Propel Rails orchestrates PropelApi installation with coordinated configuration:

# Orchestrated installation with shared configuration
rails generate propel:install
# Automatically configures API with authentication integration

PropelAuth Integration

Coordinates JWT authentication setup with API integration:

# Authentication routes automatically integrate with API versioning
rails generate propel:install --api-version=v2
# Creates /api/v2/auth/* routes

PropelFacets Integration

Configures facets system to work seamlessly with generated APIs:

# Facets automatically connect to API controllers
rails generate propel:install --adapter=propel_facets
# API controllers use facet rendering by default

Orchestration Features

Coordinated Installation

Component validation - Checks for required gems before installation
Dependency management - Ensures components are installed in correct order
Configuration sharing - Coordinates settings across all components
Migration management - Runs database migrations as needed

Intelligent Defaults

API versioning - Consistent versioning across all components
Namespace coordination - Shared namespacing for routes and controllers
Authentication integration - Automatic API authentication setup
Serialization coordination - Consistent JSON handling across components

Error Handling

Missing gem detection - Clear error messages for missing dependencies
Installation validation - Verifies successful component installation
Rollback support - Clean failure handling with helpful messages

Auto-Loading (Optional)

Propel Rails can automatically load available Propel gems:

# In your application, Propel Rails will detect and load:
require 'propel_rails'

# Automatically attempts to require:
# - propel_auth
# - propel_api  
# - propel_facets

# Gracefully handles missing gems with development notifications

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests.

# Test the meta gem
cd propel_rails
bundle exec rake test

# Test orchestration functionality
bundle exec ruby -Ilib:test test/propel_rails_test.rb

Generated Output Example

When you run rails generate propel:install, Propel Rails coordinates:

🚀 Propel Rails Framework Installation
======================================================================
Setting up your Rails application with Propel components...

📦 Installing Api component...
   ✅ PropelApi installed successfully

📦 Installing Auth component...
   ✅ PropelAuth installed successfully  

📦 Installing Facets component...
   ✅ PropelFacets installed successfully

🗃️  Running database migrations...
   ✅ Database migrations completed

🎉 Propel Installation Complete!
======================================================================

📋 Next steps:
   1. Review generated configuration files
   2. Customize API controllers and routes as needed
   3. Set up authentication flows
   4. Test your API endpoints

🔗 Useful commands:
   rails generate propel_api:controller ModelName  # Generate API controller
   rails routes                                    # View generated routes
   rails console                                   # Test models and APIs

Architecture

Propel Rails serves as the coordination layer for the Propel ecosystem:

┌─────────────────┐
│   Propel Rails  │  ← Meta gem orchestrator
└─────────────────┘
         │
    ┌────┴────┐
    │ Install │  ← Coordinated installation
    │ Generator│
    └────┬────┘
         │
    ┌────▼────┬──────────┬──────────────┐
    │PropelApi│PropelAuth│PropelFacets │ ← Individual gems
    └─────────┴──────────┴──────────────┘
         │         │           │
    ┌────▼────┬────▼────┬─────▼─────┐
    │   API   │  Auth   │  Facets   │     ← Extracted runtime
    │Controllers│ System │  System  │
    └─────────┴─────────┴───────────┘

Version Management

The meta gem coordinates version compatibility across components:

# propel_rails.gemspec includes coordinated dependencies:
# spec.add_dependency "propel_auth", "~> #{Propel::Rails::VERSION}"
# spec.add_dependency "propel_api", "~> #{Propel::Rails::VERSION}"
# spec.add_dependency "propel_facets", "~> #{Propel::Rails::VERSION}"

Self-Extracting Benefits

While Propel Rails remains as a coordinator, it manages self-extracting components:

No runtime bloat - Individual components extract and remove themselves
Coordinated setup - Single command installs entire framework
Flexible deployment - Choose components needed for each project
Unified configuration - Shared settings across all components

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/propel-web/propel_rails.

License

The gem is available as open source under the terms of the MIT License.