# hlascelles/figjam architecture

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

- Interactive diagram: https://gitdiagram.com/hlascelles/figjam
- Repository: https://github.com/hlascelles/figjam

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        FigjamCLI["bin/figjam"]:::cli
        FigaroCLI["bin/figaro"]:::cli
        CLI_Module["Figjam::CLI<br/>(lib/figjam/cli.rb)"]:::cli
        InstallCmd["Install Command<br/>(lib/figjam/cli/install.rb)"]:::cli
        TaskCmd["Task Command<br/>(lib/figjam/cli/task.rb)"]:::cli
        Template["application.yml Template<br/>(lib/figjam/cli/install/application.yml)"]:::cli
    end

    FigjamCLI -->|invokes| CLI_Module
    FigaroCLI -->|invokes| CLI_Module
    CLI_Module -->|calls| InstallCmd
    CLI_Module -->|calls| TaskCmd
    InstallCmd -->|generates| Template

    %% Core Layer
    subgraph "Core Layer"
        ConfigFile["config/application.yml"]:::externalDoc
        Parser["YAML Parser (Psych)"]:::core
        Application["Figjam::Application<br/>(lib/figjam/application.rb)"]:::core
        EnvStore["ENV Store<br/>(Ruby ENV)"]:::external
        Proxy["Figjam.env Proxy<br/>(lib/figjam/env.rb)"]:::core
    end

    ConfigFile -->|reads| Parser
    Parser -->|parses| Application
    Application -->|loads into| EnvStore
    EnvStore -->|access via| Proxy

    %% Integration Layer
    subgraph "Rails Integration"
        IntegrationPt["lib/figjam/rails.rb"]:::integr
        Railtie["Railtie<br/>(lib/figjam/rails/railtie.rb)"]:::integr
        RailsAppHook["Rails Hook<br/>(lib/figjam/rails/application.rb)"]:::integr
    end

    IntegrationPt -->|registers| Railtie
    Railtie -->|hooks into| RailsAppHook
    RailsAppHook -->|instantiates| Application

    %% Client Application
    ClientApp["Client Application<br/>(Rails or Ruby)"]:::client
    ClientApp -->|reads via| Proxy

    %% Click Events
    click FigjamCLI "https://github.com/hlascelles/figjam/tree/master/bin/figjam"
    click FigaroCLI "https://github.com/hlascelles/figjam/tree/master/bin/figaro"
    click CLI_Module "https://github.com/hlascelles/figjam/blob/master/lib/figjam/cli.rb"
    click InstallCmd "https://github.com/hlascelles/figjam/blob/master/lib/figjam/cli/install.rb"
    click TaskCmd "https://github.com/hlascelles/figjam/blob/master/lib/figjam/cli/task.rb"
    click Template "https://github.com/hlascelles/figjam/blob/master/lib/figjam/cli/install/application.yml"
    click Application "https://github.com/hlascelles/figjam/blob/master/lib/figjam/application.rb"
    click Proxy "https://github.com/hlascelles/figjam/blob/master/lib/figjam/env.rb"
    click IntegrationPt "https://github.com/hlascelles/figjam/blob/master/lib/figjam/rails.rb"
    click Railtie "https://github.com/hlascelles/figjam/blob/master/lib/figjam/rails/railtie.rb"
    click RailsAppHook "https://github.com/hlascelles/figjam/blob/master/lib/figjam/rails/application.rb"

    %% Styles
    classDef cli fill:#fff3cd,stroke:#ffec99,stroke-width:1px
    classDef core fill:#cfe2ff,stroke:#9ec5fe,stroke-width:1px
    classDef integr fill:#d1e7dd,stroke:#a3cfbb,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#b7b7b7,stroke-width:1px,stroke-dasharray: 5 5
    classDef externalDoc fill:#f8d7da,stroke:#f5c2c7,stroke-width:1px
    classDef client fill:#e7e6ff,stroke:#c5b3ff,stroke-width:1px
```
