• Overview
• Tech Stack
• Features
• Requirements
• Setup Instructions
• Development Tools
• Deployment
• Directory Structure
• Architecture Notes
• Key Files
• License

TitanCoffeeRunRails is a Ruby on Rails web application designed to manage and streamline group coffee runs for teams or organizations. It allows users to create coffee runs, join orders, and track deliveries efficiently.

• Ruby: 3.3.6
• Rails: 8.0.0
• Database: SQLite3 (all environments with multi-database setup)
• Frontend: Hotwire (Turbo + Stimulus), Import Maps
• Asset Pipeline: Propshaft
• Web Server: Puma
• Background Jobs: Solid Queue
• Caching: Solid Cache
• WebSockets: Solid Cable
• Deployment: Kamal with Docker
• HTTP Acceleration: Thruster

• PWA support with service worker and manifest
• Modern Rails 8 architecture with Solid gems
• Docker-based deployment with Kamal
• Multi-database setup (primary, cache, queue, cable)
• Import maps for JavaScript management (no Node.js/Yarn required)
• Code quality tools (RuboCop, Brakeman)
• System testing with Capybara and Selenium

• Ruby: 3.3.6 (see .ruby-version)
• Rails: 8.0.0
• Database: SQLite3 2.1+
• Docker: For deployment (optional for development)

Use the automated setup script for the easiest installation:

./scripts/runRails.sh

The script will automatically:

• ✅ Check and install Ruby 3.3.6 (via rbenv if available)
• ✅ Install bundler and dependencies
• ✅ Set up all databases (primary, cache, queue, cable)
• ✅ Run optional tests and code quality checks
• ✅ Launch the Rails server

If you prefer manual setup or need to troubleshoot:

1. Clone the repository:

   git clone <repo-url>
   cd TitanCoffeeRunRails

2. Install dependencies:

   bundle install

3. Database setup:

   rails db:setup
   # This sets up multiple databases: primary, cache, queue, and cable

4. Run the server:

   rails server

5. Access the app:

   Visit http://localhost:3000

Run tests:

rails test

Code quality checks:

bin/rubocop    # Ruby style guide
bin/brakeman   # Security analysis

Background jobs: Solid Queue runs in-process with Puma by default (see SOLID_QUEUE_IN_PUMA=true)

This app uses Kamal for Docker-based deployment:

bin/kamal setup    # Initial deployment
bin/kamal deploy   # Deploy updates
bin/kamal console  # Access Rails console
bin/kamal logs     # View logs

Configuration:

• Edit config/deploy.yml for deployment settings
• Set secrets in .kamal/secrets
• Uses SQLite with persistent Docker volumes
• SSL termination via proxy with Let's Encrypt

TitanCoffeeRunRails/
├── README.md
├── Gemfile
├── Gemfile.lock
├── Rakefile
├── config.ru
├── LICENSE
├── .ruby-version
├── .gitignore
├── .rubocop.yml
├── app/
│   ├── assets/
│   │   ├── images/
│   │   ├── stylesheets/
│   │   │   ├── application.css
│   │   │   └── css/
│   │   │       └── styles.css
│   │   └── javascripts/
│   │       ├── application.js
│   │       ├── cart.js
│   │       ├── checkout.js
│   │       ├── login.js
│   │       ├── qualify.js
│   │       ├── rotator.js
│   │       ├── sales-graph.js
│   │       └── style.js
│   ├── controllers/
│   │   ├── application_controller.rb
│   │   └── concerns/
│   ├── helpers/
│   │   └── application_helper.rb
│   ├── javascript/
│   │   ├── application.js
│   │   └── controllers/
│   │       ├── application.js
│   │       ├── hello_controller.js
│   │       └── index.js
│   ├── jobs/
│   │   └── application_job.rb
│   ├── mailers/
│   │   └── application_mailer.rb
│   ├── models/
│   │   ├── application_record.rb
│   │   └── concerns/
│   └── views/
│       ├── layouts/
│       │   ├── application.html.erb
│       │   ├── mailer.html.erb
│       │   └── mailer.text.erb
│       └── pwa/
│           ├── manifest.json.erb
│           └── service-worker.js
├── bin/
│   ├── brakeman
│   ├── bundle
│   ├── dev
│   ├── docker-entrypoint
│   ├── importmap
│   ├── jobs
│   ├── kamal
│   ├── rails
│   ├── rake
│   ├── rubocop
│   ├── setup
│   └── thrust
├── config/
│   ├── application.rb
│   ├── boot.rb
│   ├── cable.yml
│   ├── cache.yml
│   ├── database.yml
│   ├── deploy.yml
│   ├── environment.rb
│   ├── importmap.rb
│   ├── puma.rb
│   ├── queue.yml
│   ├── recurring.yml
│   ├── routes.rb
│   ├── storage.yml
│   ├── environments/
│   │   ├── development.rb
│   │   ├── production.rb
│   │   └── test.rb
│   ├── initializers/
│   │   ├── assets.rb
│   │   ├── content_security_policy.rb
│   │   ├── filter_parameter_logging.rb
│   │   └── inflections.rb
│   └── locales/
│       └── en.yml
├── db/
│   ├── cable_schema.rb
│   ├── cache_schema.rb
│   ├── queue_schema.rb
│   ├── seeds.rb
│   └── migrate/
│       └── 20250707002701_create_credit_applications.rb
├── lib/
│   └── tasks/
├── log/
├── public/
│   ├── 400.html
│   ├── 404.html
│   ├── 406-unsupported-browser.html
│   ├── 422.html
│   ├── 500.html
│   ├── icon.png
│   ├── icon.svg
│   └── robots.txt
├── script/
├── storage/
├── test/
│   ├── application_system_test_case.rb
│   ├── test_helper.rb
│   ├── controllers/
│   ├── fixtures/
│   │   └── files/
│   ├── helpers/
│   ├── integration/
│   ├── mailers/
│   ├── models/
│   └── system/
├── tmp/
│   ├── pids/
│   └── storage/
└── vendor/
    └── javascript/

• PWA: Manifest and service worker in app/views/pwa/
• Assets: Original JS/CSS migrated to app/assets/javascripts/ and app/assets/stylesheets/css/
• JavaScript: Dual approach - traditional asset pipeline for migrated code + import maps for modern Rails features
• Multi-DB: Separate SQLite databases for different concerns
• Solid Stack: Uses Rails 8's new Solid gems for queue, cache, and cable
• Docker: Containerized with Kamal for simple deployment

• scripts/runRails.sh - Automated setup and launch script
• config/deploy.yml - Kamal deployment configuration
• config/importmap.rb - JavaScript import maps
• app/views/pwa/ - Progressive Web App files
• .rubocop.yml - Ruby style configuration

Built with Rails 8 and the modern Hotwire + Solid stack.

This project integrates an existing JavaScript/HTML/CSS coffee run frontend into a Rails 8 application using Rails-first best practices. The integration transforms a localStorage-based client-side application into a full-stack Rails web application.

Authentication & Authorization:

• Devise - Industry standard authentication gem
• Pundit - Policy-based authorization system
• Admin Role System - Database-backed user permissions

Frontend Stack:

• Turbo + Stimulus - Rails 8 default Hotwire stack for SPA-like experience
• Import Maps - Modern JavaScript management without Node.js
• Propshaft - Rails 8 asset pipeline for CSS/JS/images
• ViewComponent - Reusable UI components (planned enhancement)

Database Design:

• PostgreSQL Ready - JSON fields for flexible data storage
• Multi-Model Structure - User, Product, Order, OrderItem associations
• Enum-based Status - Order lifecycle management
• Calculated Fields - Automatic total and subtotal computation

Backend Services:

• Solid Queue - Background job processing
• Solid Cache - High-performance caching
• Solid Cable - WebSocket support for real-time features
• Action Mailer - Email notifications for orders

From localStorage to Database:

• User Authentication - localStorage → Devise with encrypted passwords
• Product Catalog - Hardcoded JavaScript → Active Record models
• Shopping Cart - Client-side storage → Session-based persistence
• Order Management - Temporary data → Persistent order history
• Admin Analytics - Static charts → Dynamic database queries

Enhanced Features:

• Order Status Tracking - Pending → Confirmed → Preparing → Ready → Completed
• Donation Integration - Optional Titan Fund contributions
• Audit Trail - Created/updated timestamps for all entities
• User Profiles - Expandable user data beyond basic authentication

JSON API Endpoints:

• /api/v1/cart_items - AJAX cart management
• /api/v1/sales - Admin dashboard data feeds
• Chart.js Integration - Sales analytics visualization
• Turbo Streams - Real-time order status updates

External Services Ready:

• Payment Gateway Integration - Stripe/PayPal API placeholder
• Email Service - SendGrid/Mailgun for notifications
• SMS Notifications - Twilio integration for order updates
• Image Storage - Active Storage for product photos

Security Measures:

• CSRF Protection - Rails built-in token validation
• Parameter Filtering - Sensitive data logging prevention
• SQL Injection Prevention - Active Record query parameterization
• XSS Protection - ERB template escaping by default

Performance Optimizations:

• Database Indexing - Foreign keys and frequently queried fields
• Eager Loading - Includes for N+1 query prevention
• Fragment Caching - Product listings and static content
• Background Processing - Email delivery and heavy computations

Test Coverage:

• Model Tests - Validations, associations, business logic
• Controller Tests - Authentication, authorization, response formats
• System Tests - End-to-end user workflows with Capybara
• Integration Tests - API endpoints and service interactions

Quality Assurance:

• RuboCop - Ruby style guide enforcement
• Brakeman - Security vulnerability scanning
• SimpleCov - Code coverage reporting
• FactoryBot - Test data generation

Asset Integration:

• CSS Migration - SCSS organization into Rails asset structure
• JavaScript Conversion - Stimulus controllers for interactive elements
• Image Assets - Rails asset pipeline optimization
• Responsive Design - Mobile-first approach preservation

Template Conversion:

• HTML → ERB - Server-side rendering with Rails helpers
• Form Integration - Rails form helpers with validation
• Navigation - Shared layouts with authentication states
• Error Handling - Rails flash messages and validation display

Environment Setup:

• Docker Support - Containerized development and deployment
• Database Seeding - Sample data for development
• Environment Variables - Configuration management
• Git Hooks - Pre-commit quality checks

Deployment Pipeline:

• Kamal Integration - Docker-based production deployment
• Database Migrations - Zero-downtime schema updates
• Asset Precompilation - Optimized static file delivery
• Health Checks - Application monitoring and alerting

All setup scripts have been designed to be non-destructive and adaptive, meaning they:

• Models: Validates that model files exist and contain proper class definitions before generating new ones
• Controllers: Checks for existing controller files with correct class structures
• Routes: Analyzes existing routes and only adds missing ones, with backups
• Seeds: Preserves existing seed data and only creates new seeds if none exist
• Gems: Detects existing gems in Gemfile and avoids duplicates
• Database: Checks for existing databases, schema, and migrations before running commands

• Ruby Version: Uses rbenv if available, falls back to system Ruby, offers installation options
• Database State: Adapts to partial/complete/missing database setups
• Model Errors: Auto-fixes common Rails version compatibility issues (e.g., enum syntax)
• Dependencies: Accepts existing system tools and only installs what's missing

• Automatic Backups: Creates timestamped backups before modifying critical files
• Error Recovery: Provides recovery options when operations fail
• Validation: Syntax and structure checking before applying changes
• User Choices: Prompts for confirmation on potentially destructive operations

Each script follows this pattern:

1. Detect Environment: Check Ruby, Rails, Bundler versions
2. Analyze Existing State: Inventory what's already present
3. Plan Changes: Determine what needs to be created/modified
4. Execute Safely: Make changes with backups and validation
5. Verify Results: Confirm everything works correctly

This ensures you can run the scripts multiple times safely without corrupting existing work.

This project is licensed under the MIT License. See the LICENSE file for details.