How hlascelles/figjam works
Project Type and Purpose
• Type: An open-source Ruby gem (library + CLI tool)
• Purpose: Parse a single YAML file (config/application.yml) to load defaults and environment-specific overrides into ENV at runtime; provide a proxy (Figjam.env) to access those values; integrate automatically in Rails or be invoked manually in plain Ruby.
File Structure
Top-level:
• bin/ – CLI entry points (figjam, alias figaro, rspec)
• lib/figjam/ – Core classes:
– application.rb (YAML loader)
– cli/ (install, task)
– rails/ (Railtie + auto-load hooks)
– env.rb (proxy to ENV)
– error.rb, version, aliases, etc.
• spec/ – RSpec tests and support helpers
• figjam.gemspec, Gemfile – packaging & dependencies
• Config files: .rubocop.yml, .reek.yml, CI workflows
README for Architecture Insights
• Core flow: “Figjam::Application.new(...).load reads YAML → merges defaults + overrides → writes into ENV (unless already set) → optional warnings around type conversion.”
• Two usage patterns: automatic Rails integration via Railtie and manual invocation in arbitrary Ruby.
• Exposes Figjam.env as a getter proxy to ENV.
Main Components to Illustrate
a. CLI Layer (“bin/figjam” & “bin/figaro”)
b. Core Loader (Figjam::Application)
c. YAML Parser (Psych)
d. ENV Store (Ruby’s ENV)
e. Proxy Layer (Figjam.env)
f. Rails Integration (Figjam::Railtie)
g. Client Application (Rails app or any Ruby process)
Relationships and Data Flows
– Startup/Invocation:
• In Rails: Railtie hook → instantiate Figjam::Application with config/application.yml path → .load runs.
• In CLI or plain Ruby: user calls Figjam::Application.new(...).load.
– Processing:
1. Parser reads YAML → builds a nested hash of defaults + environment overrides
2. Loader iterates keys → for each, checks ENV first → if missing, writes the string value into ENV (emits warning if non-string in YAML)
– Access:
• Application code reads via ENV["KEY"] or Figjam.env.key / key? / key!
Architectural Patterns & Design Principles
• Modular: separates CLI, core loading logic, Rails integration, and proxy
• Single Responsibility: each class does one job (parsing, loading, interfacing)
• Inversion of Control in Rails via Railtie
• Pluggable: can be called multiple times for multiple gems/engines
Relevant Technologies & Libraries
• Ruby stdlib ENV
• psych for YAML parsing
• Rails Railtie API (for auto-load)
• Bundler & gemspec for packaging
• RSpec & Aruba for testing
Final Checklist
• [ ] All major components (CLI, core, proxy, Rails, client app) are represented
• [ ] YAML file source and ENV sink are highlighted
• [ ] Modules and classes are labeled with their file paths (e.g., lib/figjam/application.rb)