data_porter 0.1.0

data/docs/UI.md

@@ -0,0 +1,32 @@
+#### UI UX
+
+- Phlex
+- Tailwind
+
+```json
+  // tailwind.config.js (dans la gem, au build)
+ module.exports = {
+   prefix: 'dp-',
+   important: '.data-porter',
+   content: [
+     './app/views/data_porter/**/*.erb',
+     './lib/data_porter/components/**/*.rb',
+     './app/javascript/data_porter/**/*.js'
+   ],
+   corePlugins: {
+     preflight: false  // pas de reset global, on ne touche pas au host
+   },
+   theme: {
+     extend: {
+       colors: {
+         complete: 'var(--dp-color-complete, #16a34a)',
+         partial:  'var(--dp-color-partial, #ca8a04)',
+         missing:  'var(--dp-color-missing, #dc2626)',
+         primary:  'var(--dp-color-primary, #6366f1)',
+       }
+     }
+   }
+ }
+```
+
+---

data/docs/blog/001-why-build-a-data-import-engine.md

@@ -0,0 +1,166 @@
+---
+title: "Building DataPorter #1 — Why build a data import engine?"
+series: "Building DataPorter - A Data Import Engine for Rails"
+part: 1
+tags: [ruby, rails, rails-engine, gem-development, architecture, open-source]
+published: false
+---
+
+# Why build a data import engine?
+
+> Every Rails app eventually needs to import data. Let's stop rewriting the same workflow every time.
+
+## Context
+
+This is the first article in a series where we build **DataPorter**, a mountable Rails engine for data import workflows, from scratch. We'll go from `bundle gem` to a published rubygem, covering architecture decisions, DSL design, testing strategies, and everything in between.
+
+By the end of this series, you'll have a deep understanding of how to build a production-ready Rails engine — and a reusable gem to show for it.
+
+## The problem
+
+If you've worked on any non-trivial Rails application, you've probably written this code more than once:
+
+1. Upload a CSV (or fetch data from an API)
+2. Parse and validate each row
+3. Show the user what's about to be imported
+4. Persist the valid records to the database
+
+Maybe it was a guest list for a hotel app. Maybe vendor data for an e-commerce platform. Maybe scraped listings from an external API.
+
+The specifics change, but the workflow is always the same. And every time, we rebuild it from scratch: a controller action here, some CSV parsing there, a background job, maybe a progress bar if we're feeling fancy.
+
+The result? Scattered import logic across controllers, services, and jobs. No consistency. No reuse. Every new import type means rewriting the same infrastructure.
+
+## What we're building
+
+DataPorter is a mountable Rails engine that provides the entire import infrastructure. The host app only defines the business part: *what* to import and *how* to persist it.
+
+One file, one class, one import type:
+
+```ruby
+# app/importers/guests_target.rb
+class GuestsTarget < DataPorter::Target
+  label "Guests"
+  model Guest
+  sources :csv, :json
+
+  columns do
+    column :first_name, type: :string, required: true
+    column :last_name,  type: :string, required: true
+    column :email,      type: :email
+    column :phone,      type: :phone
+  end
+
+  def persist(record, context:)
+    Guest.create!(hotel: context.hotel, **record.attributes)
+  end
+end
+```
+
+That's it. DataPorter handles the rest: file upload, parsing, validation, preview UI, progress tracking, error reporting, and background processing.
+
+The workflow is always three steps:
+
+```
+Upload / Configure  →  Preview & Validate  →  Import
+```
+
+## Why not use what already exists?
+
+There are existing solutions in the Rails ecosystem. Let's look at the two most common approaches.
+
+### The DIY approach
+
+Most teams build custom import flows per model. It works, but it doesn't scale. By the third import type, you're copy-pasting controller actions and wishing you had abstracted earlier.
+
+### maintenance_tasks
+
+Shopify's [maintenance_tasks](https://github.com/Shopify/maintenance_tasks) gem is excellent for one-off data processing scripts. It provides a UI, background processing, and CSV support.
+
+But it solves a different problem. It's designed for fire-and-forget maintenance operations, not interactive import workflows.
+
+| Aspect | maintenance_tasks | DataPorter |
+|--------|-------------------|------------|
+| Purpose | One-off scripts | Import workflows |
+| Preview before import | No | Yes |
+| Visual validation | No | Yes (complete/partial/missing) |
+| Multi-step workflow | No (fire & forget) | Yes (parse -> preview -> import) |
+| Real-time progress | No | Yes (ActionCable) |
+| Data sources | CSV, ActiveRecord | CSV, JSON, API (extensible) |
+| Auto-generated UI | Parameter form | Dynamic column table |
+
+The key difference: DataPorter adds a **human validation step** between parsing and persisting. The user sees exactly what will be imported, with clear status indicators for each row, before anything touches the database.
+
+## Architecture overview
+
+DataPorter is split into two clear layers:
+
+```
+┌─────────────────────────────────────┐
+│  DataPorter (the gem)               │
+│                                     │
+│  Engine, Model, State Machine,      │
+│  Sources, Orchestrator, Jobs,       │
+│  ActionCable, UI, DSL, Registry,    │
+│  Generators                         │
+└──────────────┬──────────────────────┘
+               │ mount + configure + define targets
+┌──────────────┴──────────────────────┐
+│  Host App                           │
+│                                     │
+│  Initializer, Target files,         │
+│  Auth (parent controller),          │
+│  Style overrides (optional)         │
+└─────────────────────────────────────┘
+```
+
+The gem owns the infrastructure. The host app owns the business logic. This separation is the core design principle we'll follow throughout the series.
+
+## The tech stack
+
+Here's what we'll use and why:
+
+| Dependency | Role | Why |
+|------------|------|-----|
+| **store_model** | Typed JSONB attributes | Store import records as structured data without extra tables |
+| **phlex** | View components | Ruby-native views, easier to test and namespace than ERB |
+| **turbo-rails** | Page updates | Turbo Frames for partial reloads during the import flow |
+| **stimulus** | JS behavior | Progress bar updates via ActionCable |
+| **Tailwind CSS** | Styling | Scoped with `dp-` prefix to avoid host app conflicts |
+
+We'll also rely heavily on Rails built-ins: ActiveJob for background processing, ActionCable for real-time updates, ActiveStorage for file uploads, and enum-based state machine for the import lifecycle.
+
+## What this series covers
+
+Here's the roadmap — each part is a standalone article:
+
+1. **Why build a data import engine?** (this article)
+2. **Scaffolding a Rails Engine gem** — gem structure, Engine setup
+3. **Configuration DSL** — making the gem flexible
+4. **StoreModel & JSONB** — modeling import data without extra tables
+5. **Target DSL** — one file = one import type
+6. **CSV parsing with Sources** — the first end-to-end flow
+7. **The Orchestrator** — coordinating parse and import
+8. **ActionCable & Stimulus** — real-time progress
+9. **Phlex & Tailwind UI** — auto-generated preview tables
+10. **Controllers & routing** — engine controllers done right
+11. **Generators** — install in one command
+12. **JSON & API sources** — beyond CSV
+13. **Testing a Rails Engine** — specs for an isolated engine
+14. **Dry Run mode** — validate against the database before importing
+15. **Publishing & retrospective** — from repo to rubygems.org
+
+## Recap
+
+- Data import is a recurring pattern in Rails apps that deserves a reusable solution
+- DataPorter provides the infrastructure (upload, parse, preview, import) while the host app defines the business logic
+- The 3-step workflow with human validation is what sets it apart from existing tools
+- We're building a proper mountable Rails engine with a clean separation between gem and host app
+
+## Next up
+
+In the next article, we'll run `bundle gem data_porter`, set up the Rails Engine with `isolate_namespace`, structure our directories, and configure the gemspec with our dependencies. We'll make our first architectural decisions — and explain why they matter.
+
+---
+
+*This is part 1 of the series "Building DataPorter - A Data Import Engine for Rails". [Next: Scaffolding a Rails Engine gem](#)*

data/docs/blog/002-scaffolding-a-rails-engine.md

@@ -0,0 +1,188 @@
+---
+title: "Building DataPorter #2 — Scaffolding a Rails Engine gem"
+series: "Building DataPorter - A Data Import Engine for Rails"
+part: 2
+tags: [ruby, rails, rails-engine, gem-development, architecture]
+published: false
+---
+
+# Scaffolding a Rails Engine gem
+
+> Running `bundle gem` is just the beginning. Here's how to turn a blank gem into a proper Rails Engine with isolated namespacing, auto-loading, and a clean dependency story.
+
+## Context
+
+In [Part 1](/docs/blog/001-why-build-a-data-import-engine.md), we defined the problem DataPorter solves: a reusable, multi-step import workflow for Rails apps. We talked about architecture, the tech stack, and what sets this gem apart from existing solutions.
+
+Now it's time to write code. In this article, we'll scaffold the gem, wire up the Rails Engine, and make our first real decisions about directory structure, namespacing, and dependencies.
+
+## The problem
+
+`bundle gem data_porter` gives you a perfectly valid Ruby gem. But it gives you a Ruby gem, not a Rails Engine. There's no `config/routes.rb`, no autoloading of models or controllers, no way for a host app to mount your gem at a path. A raw gem doesn't know anything about Rails.
+
+Turning that skeleton into a mountable engine means answering a few questions upfront: How do we isolate our namespace so we don't collide with the host app? How do we structure directories so Rails autoloading works inside the gem? Which dependencies do we declare, and how tightly do we pin them?
+
+Get these wrong and you'll be fighting Rails conventions for the rest of the project. Get them right and everything else just works.
+
+## What we're building
+
+By the end of this article, the gem will have a working Engine, an isolated namespace, auto-discovery of host app import targets, and a clean gemspec. Here's the directory tree we're aiming for:
+
+```
+data_porter/
+  config/
+    routes.rb               # Engine routes (empty for now)
+  lib/
+    data_porter.rb           # Entry point: requires + module-level API
+    data_porter/
+      version.rb             # Version constant
+      engine.rb              # The Rails Engine
+      configuration.rb       # Config object (teased here, detailed in Part 3)
+  spec/
+    data_porter/
+      engine_spec.rb         # Engine specs
+  data_porter.gemspec        # Dependencies and metadata
+```
+
+This is deliberately minimal. We'll add `app/models`, `app/controllers`, and `app/views` directories as we build those layers in later articles. Rails Engine autoloading picks them up automatically once they exist, so there's no reason to create empty folders now.
+
+## Implementation
+
+### Step 1 -- The Engine class
+
+The Engine is the single most important file in a Rails Engine gem. It's the bridge between your gem and the host application's Rails stack.
+
+```ruby
+# lib/data_porter/engine.rb
+module DataPorter
+  class Engine < ::Rails::Engine
+    isolate_namespace DataPorter
+
+    config.to_prepare do
+      Dir[Rails.root.join("app/importers/*_target.rb")].each { |f| require f }
+    end
+  end
+end
+```
+
+Three things happen in these few lines, and each one matters.
+
+First, we inherit from `::Rails::Engine`. The leading `::` ensures we reference the top-level `Rails` module, not anything that might be nested under `DataPorter`. This is the line that tells Rails "this gem provides engine functionality" -- routes, autoloading, migrations, the works.
+
+Second, `isolate_namespace DataPorter` is the key architectural decision. It tells Rails to scope everything the engine provides -- routes, models, controllers -- under the `DataPorter` module. Without it, a `DataImport` model in the engine would collide with a `DataImport` model in the host app. Isolation means our table names become `data_porter_data_imports`, our routes get prefixed, and the host app stays clean.
+
+Third, the `config.to_prepare` block handles auto-discovery. We want host apps to define import targets in `app/importers/` using a simple naming convention: `*_target.rb`. The `to_prepare` callback runs before each request in development (so changes are picked up without a restart) and once at boot in production. This is the standard Rails pattern for loading code that needs to exist before the app serves requests.
+
+### Step 2 -- The entry point
+
+Every gem needs a single file that bootstraps everything. Ours is `lib/data_porter.rb`, and it sets the order of operations.
+
+```ruby
+# lib/data_porter.rb
+require "rails/engine"
+require_relative "data_porter/version"
+require_relative "data_porter/configuration"
+require_relative "data_porter/engine"
+
+module DataPorter
+  class Error < StandardError; end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end
+```
+
+The require order is intentional. We load `rails/engine` first because `DataPorter::Engine` inherits from it. Then the version (needed by the gemspec), then configuration (needed by the module-level API), then the engine itself.
+
+The `DataPorter` module also defines the gem's public API surface. `DataPorter.configure` with a block is the pattern host apps will use to customize behavior. `DataPorter::Error` gives us a base exception class to inherit from in later parts. We'll dive deep into the configuration DSL in Part 3 -- for now, the important thing is that the scaffolding is in place.
+
+Notice that we use `require_relative` for our own files and `require` for external dependencies. This is a minor but useful convention: `require_relative` is resolved from the current file's location, so it works regardless of how the gem is loaded. `require` goes through the Ruby load path, which is correct for third-party gems.
+
+### Step 3 -- The gemspec
+
+The gemspec declares what the gem needs to run and how it should be packaged. Let's look at the dependency section, which is where the real decisions live.
+
+```ruby
+# data_porter.gemspec
+Gem::Specification.new do |spec|
+  spec.name = "data_porter"
+  spec.version = DataPorter::VERSION
+  spec.required_ruby_version = ">= 3.2.0"
+
+  # ...metadata...
+
+  spec.add_dependency "rails", ">= 7.0"
+  spec.add_dependency "store_model", ">= 2.0"
+  spec.add_dependency "phlex", ">= 1.0"
+  spec.add_dependency "turbo-rails", ">= 1.0"
+end
+```
+
+Four runtime dependencies, each chosen for a specific reason.
+
+**rails >= 7.0** is the floor. We use features like `enum` improvements and `config.to_prepare` patterns that are stable from Rails 7 onward. No upper bound -- we trust semver and test against multiple Rails versions in CI.
+
+**store_model >= 2.0** lets us define typed, validatable Ruby objects backed by JSONB columns. We'll use it to model import records, errors, and reports without creating extra database tables. Part 4 covers this in detail.
+
+**phlex >= 1.0** gives us Ruby-native view components. We chose it over ViewComponent because Phlex components are plain Ruby classes -- easier to namespace, easier to test, no template files to manage inside a gem.
+
+**turbo-rails >= 1.0** provides Turbo Frames and Turbo Streams. The import workflow is a natural fit for Turbo: upload in one frame, preview in another, progress updates via streams.
+
+All version constraints use `>=` with a floor, not `~>` with a pessimistic lock. This is deliberate for a library gem. A host app should control the exact versions through its `Gemfile.lock`. If we locked `phlex ~> 1.0`, we'd block any host app that wants to use Phlex 2.x. The trade-off is that we need CI coverage across versions, but that's a solvable problem (and we'll set that up in a later article).
+
+Also worth noting: the `files` array in the gemspec uses `git ls-files` and explicitly excludes test files, bin scripts, and CI config. The published gem should only include what's needed to run it.
+
+## Decisions and tradeoffs
+
+| Decision | We chose | Over | Because |
+|----------|----------|------|---------|
+| Namespace isolation | `isolate_namespace` | Full engine (no isolation) | Prevents model/route collisions with host app |
+| Version constraints | `>= floor` (optimistic) | `~> x.y` (pessimistic) | Library gems should not lock transitive dependencies tightly |
+| Target auto-discovery | `config.to_prepare` with Dir glob | Explicit registration API | Convention over configuration; zero boilerplate for host apps |
+| View layer | Phlex | ERB / ViewComponent | Pure Ruby classes are easier to namespace and test inside a gem |
+| Require strategy | `require_relative` for internal files | `require` for everything | Resolves from file location, works regardless of load path state |
+
+## Testing it
+
+We can verify the engine is wired up correctly with a focused spec.
+
+```ruby
+# spec/data_porter/engine_spec.rb
+RSpec.describe DataPorter::Engine do
+  it "is a Rails::Engine" do
+    expect(described_class.superclass).to eq(Rails::Engine)
+  end
+
+  it "has an isolated namespace" do
+    expect(described_class.isolated?).to be true
+  end
+
+  it "is namespaced under DataPorter" do
+    expect(described_class.engine_name).to eq("data_porter")
+  end
+end
+```
+
+These three assertions confirm the fundamentals: the class hierarchy is correct, isolation is active, and the engine name Rails derives matches what we expect. The `isolated?` check is particularly important -- if someone accidentally removes the `isolate_namespace` line, this test catches it immediately.
+
+## Recap
+
+- A Rails Engine is what turns a Ruby gem into something a Rails app can mount, with routes, autoloading, and migrations.
+- `isolate_namespace` prevents name collisions between the engine and the host app. It's a one-liner, but it shapes the entire architecture.
+- The entry point (`lib/data_porter.rb`) sets up the require order and defines the gem's public API surface.
+- Gemspec dependencies should use optimistic version constraints (`>=`) so host apps stay in control of their dependency tree.
+- The `config.to_prepare` callback gives us zero-config auto-discovery of import targets in the host app.
+
+## Next up
+
+We have a working engine, but it's not configurable yet. In Part 3, we'll build the configuration DSL -- the `DataPorter.configure` block that lets host apps customize parent controllers, queue names, storage backends, and more. We'll look at why a dedicated configuration object beats scattering settings across `Rails.application.config`, and how to design defaults that make sense out of the box.
+
+---
+
+*This is part 2 of the series "Building DataPorter - A Data Import Engine for Rails". [Previous: Why build a data import engine?](/docs/blog/001-why-build-a-data-import-engine.md) | [Next: Configuration DSL](#)*
+*Code: [GitHub](https://github.com/SerylLns/data_porter)*

data/docs/blog/003-configuration-dsl.md

@@ -0,0 +1,222 @@
+---
+title: "Building DataPorter #3 — Configuration DSL: making the gem flexible"
+series: "Building DataPorter - A Data Import Engine for Rails"
+part: 3
+tags: [ruby, rails, rails-engine, gem-development, dsl, configuration, singleton-pattern]
+published: false
+---
+
+# Configuration DSL: making the gem flexible
+
+> A gem that can't adapt to its host app will never leave your own repo.
+
+## Context
+
+This is part 3 of the series where we build **DataPorter**, a mountable Rails engine for data import workflows. In [part 1](#), we established the problem and architecture. Part 2 covered scaffolding the engine gem with `isolate_namespace`.
+
+In this article, we'll build the configuration layer: a clean DSL that lets host apps customize DataPorter's behavior through an initializer. By the end, you'll have a `DataPorter.configure` block that feels like any well-designed Rails gem.
+
+## The problem
+
+Our engine needs to run inside apps we don't control. One app uses Sidekiq with a custom queue name. Another stores files on S3. A third needs every import scoped to the current hotel's account.
+
+Hard-coding any of these choices inside the gem would make it useless to anyone whose setup differs from ours. But making *everything* configurable turns the gem into a configuration puzzle where nobody remembers what goes where.
+
+The challenge is finding the line between flexibility and convention -- and expressing it through an API that feels obvious on first read.
+
+## What we're building
+
+Here's the end result from the host app's perspective:
+
+```ruby
+# config/initializers/data_porter.rb
+DataPorter.configure do |config|
+  config.parent_controller = "Admin::BaseController"
+  config.queue_name        = :low_priority
+  config.storage_service   = :amazon
+  config.preview_limit     = 200
+
+  config.context_builder = ->(controller) {
+    { hotel: controller.current_hotel, user: controller.current_user }
+  }
+end
+```
+
+This reads exactly like a Devise or Sidekiq initializer. A `configure` block yields a plain object with sensible defaults. If you don't call `configure` at all, everything still works.
+
+## Implementation
+
+### Step 1 -- The Configuration class
+
+We need an object that holds every configurable value and provides reasonable defaults out of the box. The simplest approach that works: a plain Ruby class with `attr_accessor` and defaults set in `initialize`.
+
+```ruby
+# lib/data_porter/configuration.rb
+module DataPorter
+  class Configuration
+    attr_accessor :parent_controller,
+                  :queue_name,
+                  :storage_service,
+                  :cable_channel_prefix,
+                  :context_builder,
+                  :preview_limit,
+                  :enabled_sources,
+                  :scope
+
+    def initialize
+      @parent_controller = "ApplicationController"
+      @queue_name = :imports
+      @storage_service = :local
+      @cable_channel_prefix = "data_porter"
+      @context_builder = nil
+      @preview_limit = 500
+      @enabled_sources = %i[csv json api]
+      @scope = nil
+    end
+  end
+end
+```
+
+Every attribute has a default that makes the gem work without any initializer. `parent_controller` defaults to `"ApplicationController"` because that exists in every Rails app. `storage_service` defaults to `:local` because that requires zero setup. `preview_limit` caps at 500 rows to keep the preview page responsive.
+
+Two attributes default to `nil` on purpose: `context_builder` and `scope`. These are opt-in features. When `context_builder` is nil, imports run without host-specific context. When `scope` is nil, the engine shows all imports. The gem checks for nil and adapts its behavior, rather than forcing a value that might be wrong.
+
+Let's walk through the attributes that deserve a closer look.
+
+**`parent_controller`** is a string, not a class. That's deliberate. At configuration time (during boot), the host app's controller class might not be loaded yet. We store the string and `constantize` it later, when Rails actually needs to resolve the inheritance chain.
+
+**`context_builder`** is the most interesting one. It's a lambda that receives the current controller instance and returns whatever the host app needs during import. This is how a multi-tenant app passes `current_hotel` into the import flow without the gem knowing anything about hotels. We'll use this extensively when we build the Orchestrator in part 7.
+
+**`enabled_sources`** lets the host app restrict which source types appear in the UI. If you only deal with CSV files, you can set `enabled_sources = %i[csv]` and the JSON/API options won't clutter the interface.
+
+### Step 2 -- The module-level DSL
+
+The Configuration class is just a data object. We need two module-level methods to turn it into a DSL: one to access the singleton instance, and one to yield it for configuration.
+
+```ruby
+# lib/data_porter.rb
+module DataPorter
+  class Error < StandardError; end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end
+```
+
+`configuration` uses memoization via `||=` to ensure a single instance across the application. The first call creates a `Configuration.new` with all defaults; subsequent calls return the same object. This is the singleton pattern without the ceremony of the `Singleton` module.
+
+`configure` yields that singleton to a block. Since `attr_accessor` creates both reader and writer methods, the block can set any attribute directly. After the block runs, `DataPorter.configuration.queue_name` returns whatever the host app set -- or the default if they didn't touch it.
+
+There's no `reset!` method in production code. We don't need one. The configuration is set once during Rails boot and stays put for the process lifetime. We do need to reset between tests, but that's handled with `instance_variable_set` in the spec (we'll see that in a moment).
+
+### Step 3 -- Wiring it up on boot
+
+The configuration module gets required early, before the engine loads. This ensures `DataPorter.configure` is available when the host app's initializer runs.
+
+```ruby
+# lib/data_porter.rb (top of file)
+require "rails/engine"
+require_relative "data_porter/version"
+require_relative "data_porter/configuration"
+require_relative "data_porter/engine"
+```
+
+The load order matters. `configuration.rb` comes before `engine.rb` because the Engine class might reference configuration values during setup. In practice, Rails processes initializers after the engine is loaded, so the host app's `configure` block runs with the full gem already available.
+
+Other parts of the gem read configuration like this:
+
+```ruby
+# Inside any DataPorter class
+DataPorter.configuration.queue_name
+DataPorter.configuration.context_builder&.call(controller)
+```
+
+The safe navigation operator (`&.`) on `context_builder` handles the nil default gracefully. When no builder is configured, the call simply returns nil instead of raising a NoMethodError.
+
+## Decisions & tradeoffs
+
+| Decision | We chose | Over | Because |
+|----------|----------|------|---------|
+| Configuration object | Plain class with `attr_accessor` | `OpenStruct`, `Dry::Configurable` | No dependencies, easy to read, easy to document; IDE autocompletion works with real attributes |
+| Singleton pattern | Memoized module instance variable | `Singleton` module, `Rails.application.config` | Simpler API (`DataPorter.configure`), no coupling to Rails config namespace, works in non-Rails test contexts |
+| `context_builder` type | Lambda | Block stored as proc, method object | Lambdas enforce arity (catches wrong argument count), and the syntax `->() {}` signals "this is a callable" to the reader |
+| `parent_controller` type | String | Class constant | Avoids load-order issues; the class may not exist at configuration time, but the string can be `constantize`d later |
+| Default for optional features | `nil` | Null object pattern | Simpler to check `if context_builder` than to create a no-op null object; the gem has few enough optional features to keep the nil checks manageable |
+
+## Testing it
+
+The specs verify two things: that defaults are sane, and that the `configure` block actually mutates the singleton.
+
+```ruby
+# spec/data_porter/configuration_spec.rb
+RSpec.describe DataPorter::Configuration do
+  subject(:config) { described_class.new }
+
+  it "has default parent_controller" do
+    expect(config.parent_controller).to eq("ApplicationController")
+  end
+
+  it "has default queue_name" do
+    expect(config.queue_name).to eq(:imports)
+  end
+
+  it "has default preview_limit" do
+    expect(config.preview_limit).to eq(500)
+  end
+
+  it "has nil context_builder by default" do
+    expect(config.context_builder).to be_nil
+  end
+end
+```
+
+Notice that each default gets its own test. This is intentional. When someone changes a default six months from now, the failure message says exactly which default broke, not just "configuration test failed."
+
+The module-level specs test the singleton behavior and the `configure` yield pattern:
+
+```ruby
+# spec/data_porter/configuration_spec.rb
+RSpec.describe DataPorter do
+  describe ".configure" do
+    after { DataPorter.instance_variable_set(:@configuration, nil) }
+
+    it "yields the configuration" do
+      DataPorter.configure do |config|
+        config.queue_name = :custom_queue
+      end
+
+      expect(DataPorter.configuration.queue_name).to eq(:custom_queue)
+    end
+  end
+
+  describe ".configuration" do
+    after { DataPorter.instance_variable_set(:@configuration, nil) }
+
+    it "memoizes the configuration" do
+      expect(DataPorter.configuration).to be(DataPorter.configuration)
+    end
+  end
+end
+```
+
+The `after` block resets the singleton between tests using `instance_variable_set`. This is the one place where we reach into internals, and it's acceptable because test isolation trumps encapsulation here. A public `reset!` method would leak test concerns into production code.
+
+## Recap
+
+- The `Configuration` class is a plain Ruby object with `attr_accessor` and defaults in `initialize`. No framework magic, no dependencies.
+- Two module-level methods (`configure` and `configuration`) create the DSL that host apps use in their initializer.
+- Sensible defaults mean the gem works with zero configuration. `context_builder` and `scope` are opt-in via nil defaults.
+- Storing `parent_controller` as a string avoids boot-order issues. Using a lambda for `context_builder` enforces arity and reads clearly.
+
+## Next up
+
+Configuration tells the gem *how* to behave. In part 4, we'll tackle *what* it operates on: the data models. We'll use StoreModel and JSONB columns to store import records, validation errors, and summary reports as structured data inside a single table -- no migration per import type, no schema sprawl. If you've ever debated "extra table vs. JSON column," that's the one to read.
+
+---
+
+*This is part 3 of the series "Building DataPorter - A Data Import Engine for Rails". [Previous: Scaffolding a Rails Engine gem](#) | [Next: Modeling import data with StoreModel & JSONB](#)*