fundamentalista-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 301e35254de56b06adcdbb3e168c70998e63ef0b22141c016e03206744929101
+  data.tar.gz: 715976e46da9f92cf579a9d546d91262c9712a157e23ff1ff9e96388dbd44445
+SHA512:
+  metadata.gz: f35926ae82acf6835a76aa04672e668228874d6a925d9484c0d170a07fdea270507a3c54e248563ba3d6c5ebb0a1bd7c3f9543e42055ccf761df9731eacabeab
+  data.tar.gz: b47411050fea5cdb894eae1ef9920aebccce3078fc1b3a3eb92089bbc2a8a9b6cb6c5f0cb38f9e396a3960203e64e79c894474883c5c3d295d1cb5281b7ab82d

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Mountable engine with company pages, peer comparison with the magic formula, and watchlists.
+- Holdings keep a price and take snapshots of ratios, valuation and scores, so a valuation history accumulates.
+- The fundamentalista gem uses the application's cache store by default, one day per provider response.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Costanzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+# fundamentalista-rails
+
+[![Gem Version](https://badge.fury.io/rb/fundamentalista-rails.svg)](https://rubygems.org/gems/fundamentalista-rails) [![CI](https://github.com/bruno-costanzo/fundamentalista-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/bruno-costanzo/fundamentalista-rails/actions/workflows/ci.yml)
+
+Fundamental analysis pages for your Rails application, on top of the [fundamentalista](https://github.com/bruno-costanzo/fundamentalista) gem. Mount the engine and you get company pages with statements, ratios, scores and valuation, peer comparison with the magic formula, and watchlists whose valuation snapshots build a history over time.
+
+## Installation
+
+```ruby
+gem "fundamentalista-rails"
+```
+
+```bash
+bin/rails fundamentalista_rails:install:migrations
+bin/rails db:migrate
+```
+
+Mount the engine and configure the data source. The SEC asks for a User-Agent naming your application and a contact email; Financial Modeling Prep needs an API key.
+
+```ruby
+# config/routes.rb
+mount FundamentalistaRails::Engine, at: "/fundamentals"
+
+# config/initializers/fundamentalista.rb
+Fundamentalista.configure do |config|
+  config.edgar_user_agent = "Acme Research research@acme.com"
+  config.fmp_api_key = ENV["FMP_API_KEY"]   # optional
+end
+```
+
+The engine points the gem at `Rails.cache` with a one day expiry unless you set `config.cache` yourself, so a company page costs one download and a watchlist does not hammer the SEC. Put the engine behind whatever authentication your application uses; it ships none.
+
+## Pages
+
+| Path | What it does |
+| --- | --- |
+| `/fundamentals` | Look a ticker up |
+| `/fundamentals/companies/AAPL` | Five years of statements with growth, every ratio, Piotroski, Beneish and owner earnings |
+| `/fundamentals/companies/AAPL?price=320` | The same, plus multiples, yields, Graham number, Altman Z-score, intrinsic value and implied growth at that price |
+| `/fundamentals/comparison?tickers=AAPL+MSFT+KO` | Peers side by side, with prices for the multiples, ranked by the magic formula |
+| `/fundamentals/watchlists` | Named lists of companies, each holding with the price you value it at |
+
+The pages are server rendered with a small stylesheet of their own, so they fit any application and need no assets, JavaScript or Tailwind.
+
+## Watchlists and snapshots
+
+A watchlist holds companies with a price. Taking a snapshot of a holding stores that day's ratios, valuation and scores as JSON on a `Snapshot` record, so looking at a company regularly leaves you with its valuation history, which the underlying data sources never give you for free.
+
+```ruby
+holding = FundamentalistaRails::Watchlist.find_by(name: "Quality").holdings.find_by(ticker: "AAPL")
+holding.snapshot!
+holding.snapshots.map { |snapshot| [snapshot.taken_on, snapshot.dig(:valuation, :pe)] }
+```
+
+The models are plain Active Record and yours to extend: schedule `snapshot!` from a job to build the history without visiting the page.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake    # request specs against a dummy app, and RuboCop
+```
+
+Specs stub the SEC with recorded responses; no keys are needed.
+
+## License
+
+MIT.

data/app/controllers/fundamentalista_rails/application_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Base controller of the engine: turns the gem's errors into flash
+  # messages and reads prices from parameters.
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    rescue_from Fundamentalista::CompanyNotFoundError, Fundamentalista::NoFinancialsError,
+                Fundamentalista::UnsupportedPeriodError do |error|
+      redirect_to root_path, alert: error.message
+    end
+
+    rescue_from Fundamentalista::ConfigurationError do |error|
+      render plain: error.message, status: :internal_server_error
+    end
+
+    private
+
+    def price_param(value = params[:price])
+      value.presence && BigDecimal(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/controllers/fundamentalista_rails/companies_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # The search box and the company page.
+  class CompaniesController < ApplicationController
+    def index
+      redirect_to company_path(params[:ticker].to_s.strip) if params[:ticker].present?
+    end
+
+    def show
+      @company = Fundamentalista.company(params[:ticker])
+      @financials = @company.financials(limit: 5)
+      @year = @company.latest_period
+      @price = price_param
+      @valuation = @company.valuation(price: @price) if @price
+    end
+  end
+end

data/app/controllers/fundamentalista_rails/comparisons_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Peers side by side, ranked by the magic formula.
+  class ComparisonsController < ApplicationController
+    METRICS = %i[pe fcf_yield ebit_yield roe return_on_capital net_margin debt_to_equity piotroski altman_z beneish].freeze
+
+    def show
+      @tickers = params[:tickers].to_s.split(/[\s,]+/).map(&:upcase).compact_blank
+      return if @tickers.empty?
+
+      @prices = @tickers.index_with { |ticker| price_param(params.dig(:prices, ticker)) }.compact
+      @comparison = Fundamentalista.compare(*@tickers, prices: @prices)
+      @table = @comparison.table(*METRICS)
+      @magic_formula = @comparison.magic_formula
+    end
+  end
+end

data/app/controllers/fundamentalista_rails/holdings_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Adds companies to a watchlist and removes them.
+  class HoldingsController < ApplicationController
+    def create
+      watchlist = Watchlist.find(params[:watchlist_id])
+      holding = watchlist.holdings.create!(params.require(:holding).permit(:ticker, :price))
+      redirect_to watchlist, notice: "#{holding.ticker} added"
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to watchlist, alert: e.message
+    end
+
+    def destroy
+      holding = Holding.find(params[:id])
+      holding.destroy!
+      redirect_to holding.watchlist, notice: "#{holding.ticker} removed"
+    end
+  end
+end

data/app/controllers/fundamentalista_rails/snapshots_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Takes a valuation snapshot of a holding.
+  class SnapshotsController < ApplicationController
+    def create
+      holding = Holding.find(params[:holding_id])
+      holding.snapshot!
+      redirect_to holding.watchlist, notice: "Snapshot of #{holding.ticker} taken"
+    end
+  end
+end

data/app/controllers/fundamentalista_rails/watchlists_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Lists, creates and removes watchlists.
+  class WatchlistsController < ApplicationController
+    def index
+      @watchlists = Watchlist.order(:name)
+      @watchlist = Watchlist.new
+    end
+
+    def show
+      @watchlist = Watchlist.find(params[:id])
+      @holdings = @watchlist.holdings.includes(:snapshots).order(:ticker)
+      @holding = @holdings.build
+    end
+
+    def create
+      watchlist = Watchlist.create!(params.require(:watchlist).permit(:name))
+      redirect_to watchlist
+    end
+
+    def destroy
+      Watchlist.find(params[:id]).destroy!
+      redirect_to watchlists_path, notice: 'Watchlist removed'
+    end
+  end
+end

data/app/helpers/fundamentalista_rails/figures_helper.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Formats the gem's figures for the page: rates as percentages, amounts
+  # in millions of the reporting currency, multiples with one decimal,
+  # and a dash where the filing has no figure.
+  module FiguresHelper
+    DASH = '–'
+    ACRONYMS = %w[roe roa roic ebitda ebit fcf pe ps pb ev peg sga capex eps].freeze
+
+    # Turns a metric name into a label, keeping the acronyms upper case.
+    def label(name)
+      name.to_s.humanize.gsub(/\b(#{ACRONYMS.join('|')})\b/i, &:upcase)
+    end
+
+    def percent(value)
+      value ? format('%.1f%%', value.to_f * 100) : DASH
+    end
+
+    def multiple(value)
+      value ? format('%.1fx', value.to_f) : DASH
+    end
+
+    def amount(value, currency = 'USD')
+      value ? "#{number_with_delimiter((value.to_f / 1_000_000).round)} M #{currency}" : DASH
+    end
+
+    def number(value, decimals = 2)
+      value ? number_with_precision(value.to_f, precision: decimals, delimiter: ',') : DASH
+    end
+
+    def days(value)
+      value ? "#{value.to_f.round} d" : DASH
+    end
+
+    def signal(value)
+      case value
+      when true then '✓'
+      when false then '✗'
+      else DASH
+      end
+    end
+  end
+end

data/app/models/fundamentalista_rails/application_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Base record of the engine's tables.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/fundamentalista_rails/holding.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # One company on a Watchlist, with the price used for its valuation and
+  # the Snapshots taken of it over time.
+  class Holding < ApplicationRecord
+    belongs_to :watchlist
+    has_many :snapshots, -> { order(taken_on: :desc) }, dependent: :destroy, inverse_of: :holding
+
+    validates :ticker, presence: true, uniqueness: { scope: :watchlist_id }
+
+    before_validation { self.ticker = ticker.to_s.upcase.tr('.', '-') }
+
+    # The Company behind the ticker, through the default provider.
+    def company
+      @company ||= Fundamentalista.company(ticker)
+    end
+
+    # Takes a Snapshot of the latest annual period at the holding's price.
+    def snapshot!
+      valuation = company.valuation(price: price)
+      snapshots.create!(taken_on: Date.current, price: price,
+                        figures: { ratios: valuation.period.ratios.as_json, valuation: valuation.as_json,
+                                   scores: { piotroski: valuation.period.piotroski.score, altman_z: valuation.altman_z.as_json,
+                                             beneish: valuation.period.beneish.score&.to_f } })
+    end
+  end
+end

data/app/models/fundamentalista_rails/snapshot.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # The ratios, valuation and scores of a Holding on one day, so the
+  # history of a company's valuation accumulates as you look at it.
+  class Snapshot < ApplicationRecord
+    belongs_to :holding
+
+    attribute :figures, :json
+
+    validates :taken_on, :figures, presence: true
+
+    # Returns a figure by path, such as +:valuation, :pe+.
+    def dig(*path)
+      figures.dig(*path.map(&:to_s))
+    end
+  end
+end

data/app/models/fundamentalista_rails/watchlist.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # A named list of companies to follow, each with the price you value it at.
+  class Watchlist < ApplicationRecord
+    has_many :holdings, dependent: :destroy
+
+    validates :name, presence: true
+  end
+end

data/app/views/fundamentalista_rails/companies/index.html.erb

@@ -0,0 +1,7 @@
+<% content_for :title, "Look up a company" %>
+<h1>Look up a company</h1>
+<p class="muted">Financial statements, ratios, scores and valuation from the SEC's EDGAR or Financial Modeling Prep.</p>
+<%= form_with url: root_path, method: :get, class: "inline" do |form| %>
+  <%= form.text_field :ticker, placeholder: "AAPL", "aria-label": "Ticker", autofocus: true %>
+  <%= form.button "Look up" %>
+<% end %>

data/app/views/fundamentalista_rails/companies/show.html.erb

@@ -0,0 +1,36 @@
+<% content_for :title, @company.ticker %>
+<h1><%= @company.name %> <span class="muted"><%= @company.ticker %></span></h1>
+<p class="muted">
+  Fiscal <%= @year.fiscal_year %>, ended <%= @year.ended_on %>, in <%= @year.currency %>.
+  <% if @company.cik %>CIK <%= @company.cik %>.<% end %>
+  <% if @year.bank? %>Bank.<% end %>
+</p>
+
+<%= form_with url: company_path(@company.ticker), method: :get, class: "inline" do |form| %>
+  <%= form.number_field :price, value: @price, step: "any", placeholder: "Price", "aria-label": "Price" %>
+  <%= form.button "Value at this price" %>
+<% end %>
+
+<div class="grid">
+  <section>
+    <h2>Statements</h2>
+    <%= render "fundamentalista_rails/shared/series", financials: @financials, currency: @year.currency %>
+  </section>
+
+  <section>
+    <h2>Ratios</h2>
+    <%= render "fundamentalista_rails/shared/ratios", ratios: @year.ratios, bank: @year.bank? %>
+  </section>
+
+  <section>
+    <h2>Scores</h2>
+    <%= render "fundamentalista_rails/shared/scores", period: @year, valuation: @valuation %>
+  </section>
+
+  <% if @valuation %>
+    <section>
+      <h2>Valuation at <%= number(@price) %></h2>
+      <%= render "fundamentalista_rails/shared/valuation", valuation: @valuation %>
+    </section>
+  <% end %>
+</div>

data/app/views/fundamentalista_rails/comparisons/show.html.erb

@@ -0,0 +1,41 @@
+<% content_for :title, "Compare" %>
+<h1>Compare companies</h1>
+<%= form_with url: comparison_path, method: :get, class: "inline" do |form| %>
+  <%= form.text_field :tickers, value: @tickers&.join(" "), placeholder: "AAPL MSFT KO", "aria-label": "Tickers", size: 30 %>
+  <%= form.button "Compare" %>
+<% end %>
+<% if @tickers.present? %>
+  <p class="muted">Prices, for the valuation multiples:</p>
+  <%= form_with url: comparison_path, method: :get, class: "inline" do |form| %>
+    <%= form.hidden_field :tickers, value: @tickers.join(" ") %>
+    <% @tickers.each do |ticker| %>
+      <label><%= ticker %> <%= form.number_field "prices[#{ticker}]", value: @prices[ticker], step: "any", size: 8 %></label>
+    <% end %>
+    <%= form.button "Value" %>
+  <% end %>
+<% end %>
+<% if @table %>
+  <h2>Side by side</h2>
+  <table>
+    <thead><tr><th></th><% @table.each_key do |ticker| %><th><%= link_to ticker, company_path(ticker, price: @prices[ticker]) %></th><% end %></tr></thead>
+    <tbody>
+      <% FundamentalistaRails::ComparisonsController::METRICS.each do |metric| %>
+        <tr>
+          <td><%= label(metric) %></td>
+          <% @table.each_value do |row| %>
+            <% value = row[metric] %>
+            <td>
+              <% case metric
+                 when :pe, :debt_to_equity then %><%= multiple(value) %><%
+                 when :piotroski then %><%= value || "–" %><%
+                 when :altman_z, :beneish then %><%= number(value) %><%
+                 else %><%= percent(value) %><% end %>
+            </td>
+          <% end %>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+  <h2>Magic formula</h2>
+  <p>Greenblatt's rank, best first: <strong><%= @magic_formula.join(" › ") %></strong></p>
+<% end %>

data/app/views/fundamentalista_rails/shared/_ratios.html.erb

@@ -0,0 +1,23 @@
+<% groups = { "Profitability" => Fundamentalista::Ratios::PROFITABILITY, "Liquidity" => Fundamentalista::Ratios::LIQUIDITY,
+              "Leverage" => Fundamentalista::Ratios::LEVERAGE, "Efficiency" => Fundamentalista::Ratios::EFFICIENCY,
+              "Working capital" => Fundamentalista::Ratios::WORKING_CAPITAL, "Cash" => Fundamentalista::Ratios::CASH } %>
+<% groups["Banking"] = Fundamentalista::Ratios::BANKING if bank %>
+<% rates = Fundamentalista::Ratios::PROFITABILITY + %i[debt_to_assets fcf_margin capex_to_revenue accrual_ratio net_interest_margin efficiency_ratio cost_of_risk allowance_to_loans loan_to_deposit] %>
+<table>
+  <tbody>
+    <% groups.each do |group, names| %>
+      <tr><th colspan="2" style="text-align:left"><%= group %></th></tr>
+      <% names.each do |name| %>
+        <% value = ratios.public_send(name) %>
+        <tr>
+          <td><%= label(name) %></td>
+          <td>
+            <% if Fundamentalista::Ratios::WORKING_CAPITAL.include?(name) %><%= days(value) %>
+            <% elsif rates.include?(name) %><%= percent(value) %>
+            <% else %><%= multiple(value) %><% end %>
+          </td>
+        </tr>
+      <% end %>
+    <% end %>
+  </tbody>
+</table>

data/app/views/fundamentalista_rails/shared/_scores.html.erb

@@ -0,0 +1,16 @@
+<% piotroski = period.piotroski %>
+<% beneish = period.beneish %>
+<table>
+  <tbody>
+    <tr><td>Piotroski F-score</td><td><strong><%= piotroski.score %></strong> / 9</td></tr>
+    <% piotroski.signals.each do |name, value| %>
+      <tr><td class="muted">&nbsp;&nbsp;<%= label(name) %></td><td><%= signal(value) %></td></tr>
+    <% end %>
+    <tr><td>Beneish M-score</td><td><%= number(beneish.score) %> <span class="muted"><%= beneish.likely_manipulator? ? "flagged" : (beneish.score ? "clear" : "") %></span></td></tr>
+    <% if valuation %>
+      <% z = valuation.altman_z %>
+      <tr><td>Altman Z-score</td><td><%= number(z.score) %> <span class="zone-<%= z.zone %>"><%= z.zone %></span></td></tr>
+    <% end %>
+    <tr><td>Owner earnings</td><td><%= amount(period.owner_earnings, period.currency) %></td></tr>
+  </tbody>
+</table>

data/app/views/fundamentalista_rails/shared/_series.html.erb

@@ -0,0 +1,17 @@
+<% metrics = { revenue: "Revenue", operating_income: "Operating income", net_income: "Net income", free_cash_flow: "Free cash flow", equity: "Equity", total_debt: "Total debt", eps_diluted: "Diluted EPS" } %>
+<table>
+  <thead>
+    <tr><th></th><% financials.each do |period| %><th><%= period.fiscal_year %></th><% end %><th>CAGR</th></tr>
+  </thead>
+  <tbody>
+    <% metrics.each do |metric, label| %>
+      <tr>
+        <td><%= label %></td>
+        <% financials.each do |period| %>
+          <td><%= metric == :eps_diluted ? number(period.metric(metric)) : amount(period.metric(metric), currency) %></td>
+        <% end %>
+        <td><%= percent(financials.growth(metric)) %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/fundamentalista_rails/shared/_valuation.html.erb

@@ -0,0 +1,16 @@
+<table>
+  <tbody>
+    <tr><td>Market cap</td><td><%= amount(valuation.market_cap, valuation.period.currency) %></td></tr>
+    <tr><td>Enterprise value</td><td><%= amount(valuation.enterprise_value, valuation.period.currency) %></td></tr>
+    <% Fundamentalista::Valuation::MULTIPLES.each do |name| %>
+      <tr><td><%= label(name) %></td><td><%= multiple(valuation.public_send(name)) %></td></tr>
+    <% end %>
+    <% Fundamentalista::Valuation::YIELDS.each do |name| %>
+      <tr><td><%= label(name) %></td><td><%= percent(valuation.public_send(name)) %></td></tr>
+    <% end %>
+    <tr><td>Book value per share</td><td><%= number(valuation.book_value_per_share) %></td></tr>
+    <tr><td>Graham number</td><td><%= number(valuation.graham_number) %></td></tr>
+    <tr><td>Intrinsic value (6% growth, 9% discount)</td><td><%= number(valuation.intrinsic_value(growth: 0.06, discount_rate: 0.09)) %></td></tr>
+    <tr><td>Implied growth at 9% discount</td><td><%= percent(valuation.implied_growth(discount_rate: 0.09)) %></td></tr>
+  </tbody>
+</table>

data/app/views/fundamentalista_rails/watchlists/index.html.erb

@@ -0,0 +1,19 @@
+<% content_for :title, "Watchlists" %>
+<h1>Watchlists</h1>
+<%= form_with model: @watchlist, url: watchlists_path, class: "inline" do |form| %>
+  <%= form.text_field :name, placeholder: "Quality compounders", "aria-label": "Name" %>
+  <%= form.button "Create" %>
+<% end %>
+<% if @watchlists.any? %>
+  <table>
+    <tbody>
+      <% @watchlists.each do |watchlist| %>
+        <tr>
+          <td><%= link_to watchlist.name, watchlist %></td>
+          <td><%= pluralize(watchlist.holdings.size, "company") %></td>
+          <td><%= button_to "Remove", watchlist, method: :delete, class: "quiet" %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

data/app/views/fundamentalista_rails/watchlists/show.html.erb

@@ -0,0 +1,29 @@
+<% content_for :title, @watchlist.name %>
+<h1><%= @watchlist.name %></h1>
+<%= form_with model: [@watchlist, @holding], class: "inline" do |form| %>
+  <%= form.text_field :ticker, placeholder: "Ticker", "aria-label": "Ticker", size: 8 %>
+  <%= form.number_field :price, placeholder: "Price", "aria-label": "Price", step: "any", size: 8 %>
+  <%= form.button "Add" %>
+<% end %>
+<% if @holdings.any? %>
+  <table>
+    <thead><tr><th>Company</th><th>Price</th><th>Snapshots</th><th>Latest P/E</th><th>Latest FCF yield</th><th>Piotroski</th><th></th></tr></thead>
+    <tbody>
+      <% @holdings.each do |holding| %>
+        <% latest = holding.snapshots.first %>
+        <tr>
+          <td><%= link_to holding.ticker, company_path(holding.ticker, price: holding.price) %></td>
+          <td><%= number(holding.price) %></td>
+          <td><%= holding.snapshots.size %><% if latest %> <span class="muted">last <%= latest.taken_on %></span><% end %></td>
+          <td><%= multiple(latest&.dig(:valuation, :pe)) %></td>
+          <td><%= percent(latest&.dig(:valuation, :fcf_yield)) %></td>
+          <td><%= latest&.dig(:scores, :piotroski) || "–" %></td>
+          <td>
+            <%= button_to "Snapshot", watchlist_holding_snapshots_path(@watchlist, holding), class: "quiet" %>
+            <%= button_to "Remove", watchlist_holding_path(@watchlist, holding), method: :delete, class: "quiet" %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

data/app/views/layouts/fundamentalista_rails/application.html.erb

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title><%= content_for?(:title) ? "#{yield(:title)} · Fundamentalista" : "Fundamentalista" %></title>
+    <%= csrf_meta_tags %>
+    <style>
+      :root { color-scheme: light dark; --line: #d4d4d8; --muted: #71717a; --accent: #2563eb; }
+      body { margin: 0; font: 15px/1.5 system-ui, sans-serif; max-width: 72rem; padding: 1.5rem; margin-inline: auto; }
+      header.site { display: flex; gap: 1.5rem; align-items: baseline; border-bottom: 1px solid var(--line); padding-bottom: .75rem; margin-bottom: 1.5rem; }
+      header.site a { color: inherit; text-decoration: none; }
+      header.site strong { font-size: 1.1rem; }
+      h1 { font-size: 1.5rem; margin: 0 0 .25rem; }
+      h2 { font-size: 1.05rem; margin: 2rem 0 .5rem; }
+      .muted { color: var(--muted); }
+      table { border-collapse: collapse; width: 100%; font-variant-numeric: tabular-nums; }
+      th, td { text-align: right; padding: .35rem .6rem; border-bottom: 1px solid var(--line); }
+      th:first-child, td:first-child { text-align: left; }
+      thead th { font-weight: 600; color: var(--muted); }
+      form.inline { display: inline-flex; gap: .5rem; align-items: center; flex-wrap: wrap; }
+      input[type=text], input[type=number] { font: inherit; padding: .35rem .5rem; border: 1px solid var(--line); border-radius: .375rem; background: transparent; color: inherit; }
+      button { font: inherit; padding: .35rem .8rem; border-radius: .375rem; border: 1px solid var(--accent); background: var(--accent); color: white; cursor: pointer; }
+      button.quiet { background: transparent; color: inherit; border-color: var(--line); }
+      .flash { padding: .5rem .75rem; border-radius: .375rem; border: 1px solid var(--line); margin-bottom: 1rem; }
+      .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(20rem, 1fr)); gap: 1.5rem 2.5rem; }
+      .zone-safe { color: #16a34a; } .zone-grey { color: #ca8a04; } .zone-distress { color: #dc2626; }
+    </style>
+  </head>
+  <body>
+    <header class="site">
+      <strong><%= link_to "Fundamentalista", root_path %></strong>
+      <%= link_to "Compare", comparison_path %>
+      <%= link_to "Watchlists", watchlists_path %>
+      <%= form_with url: root_path, method: :get, class: "inline", style: "margin-left:auto" do |form| %>
+        <%= form.text_field :ticker, placeholder: "Ticker", "aria-label": "Ticker", size: 8 %>
+        <%= form.button "Look up" %>
+      <% end %>
+    </header>
+    <% flash.each do |kind, message| %>
+      <p class="flash" data-kind="<%= kind %>"><%= message %></p>
+    <% end %>
+    <%= yield %>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+FundamentalistaRails::Engine.routes.draw do
+  root to: 'companies#index'
+  resources :companies, only: :show, param: :ticker
+  resource :comparison, only: :show
+  resources :watchlists, only: %i[index create show destroy] do
+    resources :holdings, only: %i[create destroy] do
+      resources :snapshots, only: :create
+    end
+  end
+end

data/db/migrate/20260906000000_create_fundamentalista_rails_tables.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class CreateFundamentalistaRailsTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :fundamentalista_rails_watchlists do |t|
+      t.string :name, null: false
+      t.timestamps
+    end
+
+    create_table :fundamentalista_rails_holdings do |t|
+      t.references :watchlist, null: false, foreign_key: { to_table: :fundamentalista_rails_watchlists }
+      t.string :ticker, null: false
+      t.decimal :price, precision: 20, scale: 6
+      t.timestamps
+      t.index %i[watchlist_id ticker], unique: true
+    end
+
+    create_table :fundamentalista_rails_snapshots do |t|
+      t.references :holding, null: false, foreign_key: { to_table: :fundamentalista_rails_holdings }
+      t.date :taken_on, null: false
+      t.decimal :price, precision: 20, scale: 6
+      t.text :figures, null: false
+      t.timestamps
+      t.index %i[holding_id taken_on]
+    end
+  end
+end

data/lib/fundamentalista-rails.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'fundamentalista'
+require 'rails/engine'
+require 'fundamentalista_rails/version'
+require 'fundamentalista_rails/cache'
+require 'fundamentalista_rails/engine'
+
+# Fundamental analysis inside a Rails application: an engine with company
+# pages, peer comparison and watchlists that keep valuation snapshots,
+# on top of the fundamentalista gem.
+#
+#   # config/routes.rb
+#   mount FundamentalistaRails::Engine, at: "/fundamentals"
+#
+module FundamentalistaRails
+end

data/lib/fundamentalista_rails/cache.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Keeps provider responses in the application's cache store for a day,
+  # so a company page costs one download and a screen over a watchlist
+  # does not hammer the SEC.
+  class Cache
+    attr_reader :store, :expires_in
+
+    def initialize(store, expires_in: 1.day)
+      @store = store
+      @expires_in = expires_in
+    end
+
+    def fetch(key, &)
+      store.fetch(key, expires_in: expires_in, &)
+    end
+  end
+end

data/lib/fundamentalista_rails/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # Mounts the company pages, comparisons and watchlists, and points the
+  # fundamentalista gem at the application's cache unless one is set.
+  #
+  #   mount FundamentalistaRails::Engine, at: "/fundamentals"
+  #
+  # Configure the gem in an initializer as usual; the engine only adds
+  # the cache and the migrations for watchlists.
+  class Engine < ::Rails::Engine
+    isolate_namespace FundamentalistaRails
+
+    config.after_initialize do
+      Fundamentalista.config.cache ||= Cache.new(::Rails.cache) if ::Rails.cache
+      Fundamentalista.config.logger = ::Rails.logger
+    end
+  end
+end

data/lib/fundamentalista_rails/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FundamentalistaRails
+  # The version of the fundamentalista-rails gem, as a string.
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: fundamentalista-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bruno Costanzo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fundamentalista
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'A mountable engine on top of the fundamentalista gem: look up any listed
+  company, read its statements, ratios, scores and valuation, compare peers with the
+  magic formula, and keep watchlists whose valuation snapshots build a history. Uses
+  the application cache for provider data.'
+email:
+- dev.bcostanzo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/fundamentalista_rails/application_controller.rb
+- app/controllers/fundamentalista_rails/companies_controller.rb
+- app/controllers/fundamentalista_rails/comparisons_controller.rb
+- app/controllers/fundamentalista_rails/holdings_controller.rb
+- app/controllers/fundamentalista_rails/snapshots_controller.rb
+- app/controllers/fundamentalista_rails/watchlists_controller.rb
+- app/helpers/fundamentalista_rails/figures_helper.rb
+- app/models/fundamentalista_rails/application_record.rb
+- app/models/fundamentalista_rails/holding.rb
+- app/models/fundamentalista_rails/snapshot.rb
+- app/models/fundamentalista_rails/watchlist.rb
+- app/views/fundamentalista_rails/companies/index.html.erb
+- app/views/fundamentalista_rails/companies/show.html.erb
+- app/views/fundamentalista_rails/comparisons/show.html.erb
+- app/views/fundamentalista_rails/shared/_ratios.html.erb
+- app/views/fundamentalista_rails/shared/_scores.html.erb
+- app/views/fundamentalista_rails/shared/_series.html.erb
+- app/views/fundamentalista_rails/shared/_valuation.html.erb
+- app/views/fundamentalista_rails/watchlists/index.html.erb
+- app/views/fundamentalista_rails/watchlists/show.html.erb
+- app/views/layouts/fundamentalista_rails/application.html.erb
+- config/routes.rb
+- db/migrate/20260906000000_create_fundamentalista_rails_tables.rb
+- lib/fundamentalista-rails.rb
+- lib/fundamentalista_rails/cache.rb
+- lib/fundamentalista_rails/engine.rb
+- lib/fundamentalista_rails/version.rb
+homepage: https://github.com/bruno-costanzo/fundamentalista-rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bruno-costanzo/fundamentalista-rails
+  changelog_uri: https://github.com/bruno-costanzo/fundamentalista-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bruno-costanzo/fundamentalista-rails/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Fundamental analysis pages for Rails: companies, comparisons and watchlists.'
+test_files: []