# thoughtbot/factory_bot architecture

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

- Interactive diagram: https://gitdiagram.com/thoughtbot/factory_bot
- Repository: https://github.com/thoughtbot/factory_bot

## Overview

##### Main Components
- Client Code / Integration Layer – This represents the consumer of the gem (e.g., Rails, RSpec, or other Ruby applications that use factory_bot). It calls the public APIs to define and build object factories.
- Public API / DSL Interface – Located primarily in lib/factory_bot and its syntax subdirectories (such as lib/factory_bot/syntax). This component exposes the DSL methods that clients use to define factories and traits.
- Core Factory Engine – This includes modules for defining and managing factories (for example, lib/factory_bot/factory, lib/factory_bot/registry, lib/factory_bot/definition, and lib/factory_bot/definition_proxy). It holds the logic for registering, finding, and inheriting definitions.
- Build Strategies & Evaluation – Group together the modules handling different strategies (found under lib/factory_bot/strategy with files like build.rb, create.rb, stub.rb, and attributes_for.rb). Also include evaluation and strategy selection elements (e.g., lib/factory_bot/evaluator, lib/factory_bot/strategy_calculator) that decide how an instance is built based on the chosen strategy.
- Attribute and Sequence Handling – Components such as lib/factory_bot/attribute, lib/factory_bot/attribute/sequence, and lib/factory_bot/sequence are responsible for generating dynamic attributes and managing sequences.
- Callbacks & Hooks – The modules that handle callback logic (like lib/factory_bot/callback and lib/factory_bot/callbacks_observer) ensure that lifecycle hooks are applied during object construction.
- Error Handling, Linting, and Internal Utilities – This includes elements like lib/factory_bot/errors, lib/factory_bot/linter, and supporting modules that provide internal integrity checks.

##### Relationships and Interactions
- A flow starting from the Client Code invoking the DSL methods from the Public API, which then delegates to the Core Factory Engine.
- That the Core Engine registers factory definitions in the registry and uses the Attribute/Sequence components to generate attribute data.
- That, upon building an instance, the engine selects a Build Strategy (for example, build vs. create vs. stub) which then triggers the Evaluation and Strategy Calculator components.
- That Callbacks or Hooks are invoked at key stages during the object-building lifecycle.

##### Architectural Patterns and Design Principles
- Use of the Strategy Pattern for selecting among various build approaches.
- Separation of concerns by dividing the DSL/API layer, factory definition/registration module, and build/evaluation components.
- Emphasis on modularity and extensibility: Each of these modules (for attribute handling, sequence generation, associations, and callbacks) is kept separate.
- Clear differentiation between the public interface (what the user directly interacts with) and internal mechanisms (factory registration, definition processing, evaluation).

##### Specific Technologies and Frameworks
- Ruby as the primary programming language and gem packaging.
- Integration/invocation via testing frameworks such as RSpec (as seen in the spec/ directory) and usage with Rails (via the separate factory_bot_rails gem).

##### Final Details
- Given that the project has a rich set of tests and documentation (reflected in both spec and docs directories), these assure us that modular boundaries have been well considered.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Integration Layer"
        Client["Client Code / Test Suites"]:::integration
    end

    subgraph "Public Interface"
        API["Public DSL API"]:::public
    end

    subgraph "Internal Engine"
        CoreEngine["Factory Definition & Registry"]:::core
        AttrSeq["Attribute & Sequence Handlers"]:::attribute
        BuildStrategy["Build Strategies & Evaluation"]:::strategy
        Callbacks["Callbacks & Hooks"]:::callback
        ErrorUtil["Error Handling, Linting, and Internal Utilities"]:::error
    end

    Client -->|"invokes"| API
    API -->|"registers"| CoreEngine
    CoreEngine -->|"generates"| AttrSeq
    CoreEngine -->|"selects"| BuildStrategy
    BuildStrategy -->|"applies_callbacks"| Callbacks
    API -->|"configures"| ErrorUtil
    CoreEngine -->|"checks"| ErrorUtil

    %% Click Events
    click Client "https://github.com/thoughtbot/factory_bot/tree/main/spec/"
    
    click API "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot.rb"
    click API "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/syntax/default.rb"
    click API "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/syntax/methods.rb"

    click CoreEngine "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/factory.rb"
    click CoreEngine "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/registry.rb"
    click CoreEngine "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/definition.rb"
    click CoreEngine "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/definition_proxy.rb"

    click BuildStrategy "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/strategy/build.rb"
    click BuildStrategy "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/strategy/create.rb"
    click BuildStrategy "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/strategy/stub.rb"
    click BuildStrategy "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/strategy/attributes_for.rb"
    click BuildStrategy "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/evaluator.rb"
    click BuildStrategy "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/strategy_calculator.rb"

    click AttrSeq "https://github.com/thoughtbot/factory_bot/tree/main/lib/factory_bot/attribute"
    click AttrSeq "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/attribute/sequence.rb"
    click AttrSeq "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/sequence.rb"

    click Callbacks "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/callback.rb"
    click Callbacks "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/callbacks_observer.rb"

    click ErrorUtil "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/errors.rb"
    click ErrorUtil "https://github.com/thoughtbot/factory_bot/blob/main/lib/factory_bot/linter.rb"

    %% Styles
    classDef integration fill:#AEDFF7,stroke:#1f78b4,stroke-width:2px;
    classDef public fill:#C2FABC,stroke:#228B22,stroke-width:2px;
    classDef core fill:#FFE699,stroke:#FFB90F,stroke-width:2px;
    classDef strategy fill:#FDD7E4,stroke:#FF69B4,stroke-width:2px;
    classDef attribute fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
    classDef callback fill:#F0E68C,stroke:#DAA520,stroke-width:2px;
    classDef error fill:#FFCCCB,stroke:#FF0000,stroke-width:2px;
```
