# github/scientist architecture

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

- Interactive diagram: https://gitdiagram.com/github/scientist
- Repository: https://github.com/github/scientist

## Overview

##### Project Type and Purpose
- This is a Ruby library (a gem) named “Scientist” that instruments your application code to run two behaviors (“control” and “candidate”) side-by-side, compare their results, measure timing, and publish mismatches or metrics.
- It’s not a web app or microservice; it’s a pluggable library that your own Ruby code includes to wrap critical paths during refactoring.

##### File Structure Highlights
- Top-level:
- .github/, CI config
- Gemfile, scientist.gemspec – gem packaging
- lib/scientist.rb – entry point requiring sub-modules
- lib/scientist/experiment.rb, default.rb, observation.rb, result.rb – core components
- test/ – unit tests for all core behaviors
- script/ – helper scripts for bootstrapping, testing, releasing
- There are no frontend/backend folders or external services built-in; the gem defers publishing to user-provided `publish` implementations (e.g., StatsD, Redis).

##### Key Architecture from the README
- Public API:
- `include Scientist` → adds `science` helper to your class
- `Scientist.run` → alternative entry for non-module usage
- Core Modules:
- Scientist::Default – default experiment implementation
- Scientist::Experiment – mix-in that defines `enabled?`, `publish`, `compare`, etc.
- Scientist::Observation – encapsulates one run of control/candidate blocks
- Scientist::Result – aggregates observations, provides metrics (matched, mismatched, durations)
- Extensibility: Users supply their own Experiment classes (override `enabled?`, `publish`, `raised`, etc.).

a. Main Components
- User Application Code (your classes/modules)
- Scientist Public API (`science` helper, `Scientist.run`)
- Experiment Factory (default or custom): instantiates Experiment objects
- Scientist::Experiment module (mixin): defines lifecycle hooks
- Control & Candidate Blocks (closures provided by user code)
- Observation & Result objects
- Publishing Targets (StatsD, Redis, custom sink)
- Test Harness (scripts and test suite with `raise_on_mismatches`)
b. Component Interactions
1. User calls `science("name") { |e| e.use{...}; e.try{...} }`
2. The API loads the default Experiment implementation (or a custom one)
3. Experiment#run:
- Checks `run_if` → `enabled?`
- Randomizes execution order of control & candidate
- Wraps each block in an Observation → records durations, exceptions
- Compares results via `compare` / `compare_errors`
- Aggregates Observations into a Result
- Calls `publish(result)`
4. `publish` method pushes metrics to external systems (e.g., StatsD, Redis)
5. Test suite toggles `raise_on_mismatches` to convert mismatches into test failures
c. Architectural Patterns & Principles
- Mixins (Scientist module and Scientist::Experiment module) for clean API extension
- Dependency Injection for custom Experiment classes
- Immutable value objects (Observation, Result) to model run data
- Randomized sequencing to avoid bias in timing measurements
- Callback hooks (before_run, compare, compare_errors, ignore, clean)
d. Relevant Technologies
- Ruby 2.3+
- Bundler / Gemfile / gems
- Rake & script tasks for CI, testing, releasing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        UA["App Code"]:::app
    end

    %% Scientist Gem Core
    subgraph "Scientist Gem Core"
        API["Scientist Public API\n(include Scientist, Scientist.run)"]:::core
        Factory["Experiment Factory\n(Default or Custom)"]:::core
        Default["Scientist::Default"]:::core
        Experiment["Scientist::Experiment Mixin"]:::core
        Observation["Scientist::Observation"]:::core
        Result["Scientist::Result"]:::core
        Errors["Scientist::Errors"]:::core
        Version["Scientist::VERSION"]:::core
        GemSpec["Gem Specification\n(scientist.gemspec)"]:::core
    end

    %% External Publishers
    subgraph "External Publishers"
        Publisher["Publisher Hook"]:::core
        StatsD["StatsD"]:::extsvc
        Redis["Redis"]:::extsvc
        CustomSink["Custom Sink"]:::extsvc
    end

    %% Test & CI
    subgraph "Test & CI"
        Test["Test Harness\ntest/scientist/"]:::infra
        Scripts["Helper Scripts\nscript/"]:::infra
        CI["CI Config\n.github/workflows/ci.yml"]:::infra
    end

    %% Data Flows
    UA -->|"science(name){…}"| API
    API -->|"select Experiment impl."| Factory
    Factory --> Default
    Factory -->|"or custom" | Experiment
    Default --> Experiment
    Experiment -->|"wrap blocks"| Observation
    Observation -->|"collect data"| Result
    Result -->|"publish(result)"| Publisher
    Publisher --> StatsD
    Publisher --> Redis
    Publisher --> CustomSink
    Test -->|"raise_on_mismatches" | Experiment
    CI --> Scripts

    %% Click Events
    click API "https://github.com/github/scientist/blob/main/lib/scientist.rb"
    click Default "https://github.com/github/scientist/blob/main/lib/scientist/default.rb"
    click Experiment "https://github.com/github/scientist/blob/main/lib/scientist/experiment.rb"
    click Observation "https://github.com/github/scientist/blob/main/lib/scientist/observation.rb"
    click Result "https://github.com/github/scientist/blob/main/lib/scientist/result.rb"
    click Errors "https://github.com/github/scientist/blob/main/lib/scientist/errors.rb"
    click Version "https://github.com/github/scientist/blob/main/lib/scientist/version.rb"
    click GemSpec "https://github.com/github/scientist/blob/main/scientist.gemspec"
    click Test "https://github.com/github/scientist/tree/main/test/scientist/"
    click Scripts "https://github.com/github/scientist/tree/main/script/"
    click CI "https://github.com/github/scientist/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef app fill:#E6FFEA,stroke:#28A745,color:#28A745;
    classDef extsvc fill:#FFE8D6,stroke:#D25D00,color:#D25D00;
    classDef infra fill:#F2F2F2,stroke:#6A737D,color:#6A737D;
    classDef ext stroke-dasharray: 5 5,fill:#FFF,stroke:#8B0000,color:#8B0000;
```
