TitanCoffeeRunRails

Ruby Rails SQLite Docker Kamal PWA Hotwire License: MIT

Table of Contents

Overview

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.

Tech Stack

Features

Requirements

Setup Instructions

Use the automated setup script for the easiest installation:

./scripts/runRails.sh

The script will automatically:

Manual Setup

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

Development Tools

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)

Deployment

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:

Directory Structure

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/

Architecture Notes

Key Files

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

Project Architecture & Integration

Frontend to Rails Migration

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.

Core Architecture Decisions

Authentication & Authorization:

Frontend Stack:

Database Design:

Backend Services:

Data Model Transformation

From localStorage to Database:

Enhanced Features:

API & Integration Points

JSON API Endpoints:

External Services Ready:

Security & Performance

Security Measures:

Performance Optimizations:

Testing Strategy

Test Coverage:

Quality Assurance:

Migration from Frontend Project

Asset Integration:

Template Conversion:

Development Workflow

Environment Setup:

Deployment Pipeline:

Dependency Management & Non-Destructive Setup

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

✅ Check Before Creating

🔄 Adaptive Behavior

🛡️ Safety Features

📋 Dependency Checking Pattern

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.

License

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

This site is open source. Improve this page.