How norman/friendly_id works
Project type and purpose
• This is a Ruby gem (library) called “FriendlyId,” designed to be included in Rails applications.
• Purpose: provide ActiveRecord models with human-friendly slugs and permalinks, supporting features like history/versioning, scoped slugs, reserved words, i18n, and custom generators.
File structure
• Top-level files:
• Gemfile, friendly_id.gemspec, Rakefile → gem packaging & tasks
• README.md, CONTRIBUTING.md, UPGRADING.md, Changelog.md, MIT-LICENSE → documentation & licensing
• .github/workflows → CI config
• gemfiles/ → test matrices for different Rails versions
• lib/friendly_id/ → core code split into modules (base, slugged, history, configuration, finders, migration, etc.)
• lib/generators → Rails generator to kick off migrations & initializer
• test/ → unit tests, benchmarks, schema fixtures
README for additional insights
• Confirms gem architecture: extends ActiveRecord, generates migrations for slug table, injects finder methods, and provides a Rails generator.
• Lists features that correspond to modules (History, Scoped, Reserved, I18n, SequentiallySlugged).
Main components
a. FriendlyId Gem (core library)
• Modules: Configuration, Slugged, History, Scoped, Reserved, I18n, ObjectUtils, SequentiallySlugged, FinderMethods, SlugGenerator
• Generator/Rake tasks (lib/generators & Rakefile)
b. Host Rails Application
• ActiveRecord models (e.g., User) that extend FriendlyId
• Controllers that call Model.friendly.find
c. Database
• Primary tables (e.g., users)
• friendly_id_slugs table for slug history & versioning
d. External Dependencies
• ActiveRecord (Rails)
• Ruby runtime
Relationships and interactions
• On startup, gem’s Railtie/initializer hooks into ActiveRecord → extends models with friendly_id DSL
• When developer runs rails generate friendly_id, generator creates migration & initializer
• Migration creates friendly_id_slugs table
• At runtime, Model.friendly.find routes calls to FinderMethods → queries DB on slug column or slug history
• SlugGenerator module is invoked on model save to compute a new slug according to configuration
• History module writes previous slugs to slug history table
• Scoped module constrains slug uniqueness per scope (e.g., per parent record)
Architectural patterns & design principles
• Modular design: each feature lives in its own module under lib/friendly_id
• Plugin pattern: extends host application via ActiveSupport::Concern or extend FriendlyId
• Generator pattern: Rails generator scaffolds migrations/initializers
• Single responsibility: each module handles one aspect (e.g., history, reserved words)
• Layered design:
• Configuration layer (initialization)
• Domain layer (slug computation & persistence)
• Persistence layer (ActiveRecord hooks & migrations)
• Finder layer (query abstraction)
Elements
• FriendlyId Gem (subdivide to modules)
• Rails App (Models, Controllers)
• Database (users table, friendly_id_slugs table)
• Generator → Migration file → DB schema
• Model.save → SlugGenerator → DB write
• Controller.find → FinderMethods → DB query
• External deps (gray)