# norman/friendly_id architecture

> Architecture diagram of the GitHub repository norman/friendly_id, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/norman/friendly_id
- Repository: https://github.com/norman/friendly_id

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        RubyRuntime["Ruby Runtime"]:::external
        ActiveRecord["ActiveRecord (Rails)"]:::external
    end

    %% Host Application
    subgraph "Rails Application" 
        direction TB
        Controller["Controllers"]:::hostapp
        Model["ActiveRecord Models"]:::hostapp
    end

    %% FriendlyId Gem Core
    subgraph "FriendlyId Gem" 
        direction TB
        Entry["FriendlyId Gem\n(lib/friendly_id.rb)"]:::library
        Config["Configuration\n(lib/friendly_id/configuration.rb)"]:::library
        Slugged["Slugged Module\n(lib/friendly_id/slugged.rb)"]:::library
        History["History Module\n(lib/friendly_id/history.rb)"]:::library
        Scoped["Scoped Module\n(lib/friendly_id/scoped.rb)"]:::library
        Reserved["Reserved Words Module\n(lib/friendly_id/reserved.rb)"]:::library
        I18n["I18n Support Module\n(lib/friendly_id/simple_i18n.rb)"]:::library
        ObjUtils["Object Utilities\n(lib/friendly_id/object_utils.rb)"]:::library
        SeqSlug["SequentiallySlugged\n(lib/friendly_id/sequentially_slugged.rb)"]:::library
        SeqCalc["SeqSlug Calculator\n(lib/friendly_id/sequentially_slugged/calculator.rb)"]:::library
        Finder["FinderMethods\n(lib/friendly_id/finder_methods.rb)"]:::library
        GeneratorMod["SlugGenerator\n(lib/friendly_id/slug_generator.rb)"]:::library
        MigrationMod["Migration Support\n(lib/friendly_id/migration.rb)"]:::library
        Initializer["Railtie/Initializer\n(lib/friendly_id/initializer.rb)"]:::library
        SlugModel["Slug Model\n(lib/friendly_id/slug.rb)"]:::library
        Candidates["Candidate Generation\n(lib/friendly_id/candidates.rb)"]:::library
        Version["Gem Version\n(lib/friendly_id/version.rb)"]:::library
    end

    %% Generators and Tasks
    subgraph "Generators & Tasks"
        direction TB
        RailsGen["Rails Generator\n(lib/generators/friendly_id_generator.rb)"]:::library
        RakeTasks["Rakefile"]:::library
        Gemspec["Gem Specification\n(friendly_id.gemspec)"]:::library
    end

    %% Database
    subgraph "Database" 
        direction TB
        UsersTable["users table"]:::db
        SlugsTable["friendly_id_slugs table"]:::db
    end

    %% Relationships
    RubyRuntime -->|loads| Entry
    ActiveRecord -->|hooks via Railtie| Initializer
    Initializer -->|extends| Model
    Model -->|include DSL| Entry
    RailsGen -->|generates migration & initializer| MigrationMod
    RailsGen -->|creates migration file| SlugsTable
    Controller -->|calls friendly.find| Finder
    Finder -->|queries| UsersTable
    Finder -->|queries history| SlugsTable
    Model -->|before_save: generate slug| GeneratorMod
    GeneratorMod -->|invokes| Slugged
    Slugged -->|uses| Config
    Slugged -->|calls| Candidates
    Config -->|provides settings to| GeneratorMod
    Model -->|after_update: write history| History
    History -->|writes to| SlugsTable
    SeqSlug -->|calls| SeqCalc
    Scoped -->|enforces uniqueness| SlugsTable
    Reserved -->|filters| Candidates
    I18n -->|translates| Candidates
    MigrationMod -->|defines schema| SlugsTable

    Controller -->|receives requests| Model

    %% Click Events
    click Entry "https://github.com/norman/friendly_id/blob/master/lib/friendly_id.rb"
    click Config "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/configuration.rb"
    click Slugged "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/slugged.rb"
    click History "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/history.rb"
    click Scoped "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/scoped.rb"
    click Reserved "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/reserved.rb"
    click I18n "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/simple_i18n.rb"
    click ObjUtils "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/object_utils.rb"
    click SeqSlug "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/sequentially_slugged.rb"
    click SeqCalc "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/sequentially_slugged/calculator.rb"
    click Finder "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/finder_methods.rb"
    click GeneratorMod "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/slug_generator.rb"
    click MigrationMod "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/migration.rb"
    click Initializer "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/initializer.rb"
    click SlugModel "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/slug.rb"
    click Candidates "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/candidates.rb"
    click Version "https://github.com/norman/friendly_id/blob/master/lib/friendly_id/version.rb"
    click RailsGen "https://github.com/norman/friendly_id/blob/master/lib/generators/friendly_id_generator.rb"
    click RakeTasks "https://github.com/norman/friendly_id/tree/master/Rakefile"
    click Gemspec "https://github.com/norman/friendly_id/blob/master/friendly_id.gemspec"

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#000000
    classDef hostapp fill:#ccffcc,stroke:#2d662d,color:#000000
    classDef library fill:#cce5ff,stroke:#3366cc,color:#000000
    classDef db fill:#ffe5cc,stroke:#cc6600,color:#000000
```
