Showcase

In between updates to Agile Web Development with Rails 8, I keep my Rails skills sharp by developing small applications.

I also take ballroom dance lessons with my wife, and we have competed internationally and at smaller local competitions. For larger events there is commercial software for scheduling "heats" where dancers go on the floor and be judged. Smaller competitions use spreadsheets to track this.

Scheduling is deceptively hard, particularly if you have last minute changes such as an instructor not being able to make the competition for any reason. Manually making last minute changes can lead to scheduling mishaps, such as having the same person being scheduled twice with different partners for the same heat.

This application manages showcase events, from data entry to scheduling, to generating of printed reports. It can also be accessed by participants on the day of the event to see the list of heats, and by judges to enter scores.

Getting up and running - bare metal, one event

Prerequisites: git and ruby.

git clone https://github.com/rubys/showcase.git
cd Showcase
bundle install
bin/rails db:prepare
bin/rails test
bin/rails test:system
bin/dev

Visit http://localhost:3000/ to see the event.

Getting up and running - docker image, multiple events

Prerequisites: git, ruby, and docker.

git clone https://github.com/rubys/showcase.git
cd Showcase
bundle install
rm config/credentials.yml.enc
bin/rails credentials:edit
docker compose build
docker compose up
docker compose exec web bin/bootstrap

Note: Showcase configuration is managed via the admin interface at /admin, which stores data in db/index.sqlite3 and generates db/showcases.yml automatically.

Visit http://localhost:9999/showcase/ to see the list of events.

Implementation overview

This is pretty much a standard CRUD Rails 8.0.2 application using import maps for JavaScript and TailwindCSS for CSS. The application uses Rails 8.0 configuration defaults and has been fully migrated to be compatible with SQL reserved word quoting requirements.

Models are split into two categories:

Base models support ballroom dance event management:

• Core competition: Event (singleton config), Person (all participants, STI disabled), Studio (with pairs), Dance (with scrutineering), Category (with extensions), Age, Level
• Heat & performance: Heat (numbered sessions), Entry (connects lead/follow/instructor), Solo (routines with optional formations), Formation (individual participants), Multi, MultiLevel
• Heats are numbered - all Heat records with the same number are on the floor simultaneously. Heats with number >= 1 are scheduled; number < 0 indicates scratched (withdrawn) heats that can be restored or permanently deleted
• Split dances - when a dance appears in multiple categories, there are multiple Dance records with the same name: one with positive order (canonical), others with order < 0 that sync properties from the canonical dance
• Judging & scoring: Judge, Score (live updates via ActionCable), Recording
• Financial: Billable (packages/options, STI disabled), PackageInclude, PersonOption, Payment
• Seating: Table (grid positioning), StudioPair
• Music & questionnaires: Song, Question, Answer, Feedback

Admin models support system administration and multi-tenancy: Locale (service class), Location, Showcase, User, Region, ApplicationRecord (base class with Tigris storage integration).

The heat scheduler in app/controllers/concerns/heat_scheduler.rb uses a two-pass algorithm: first minimizing heat count, then balancing heat sizes. It interleaves different dance types within agenda categories and appends manually-ordered solos.

The table assignment system in app/controllers/concerns/table_assigner.rb and app/controllers/tables_controller.rb offers two algorithms: Regular Assignment prioritizes keeping studios together, while Pack Assignment maximizes table utilization. Both use a two-phase algorithm (Phase 1 groups people into tables, Phase 2 places tables on grid) and achieve 100% success rate for large studios (>10 people) and studio pairs. Key features include:

• Event Staff isolation (studio_id = 0 never mixed with other studios)
• Studio Pair Handling (paired studios share tables or are placed adjacent)
• Optimal table utilization (fits small studios into existing tables first)
• Global position reservation with priority system (0-3)
• Contiguous block placement for large studios
• Smart consolidation to minimize total table count
• Sequential numbering following physical grid layout (row-major order)
• Drag-and-drop grid interface for manual arrangement
• Handles option tables via person_options join table

The application is designed to scale from single events to hundreds of simultaneous events across multiple regions using a shared-nothing architecture. See ARCHITECTURE.md for details on the production deployment architecture using Navigator, Fly.io, and Tigris storage.