frankfurter AGENTS.md

Frankfurter

Frankfurter is a free and open-source currency data API built with Ruby that tracks reference exchange rates from 50+ institutional sources (central banks, the IMF, the Federal Reserve, etc.).

Before You Write Code

Several agents work in this repo at once. Assume you are not alone.

Do your work in a git worktree, not in the primary checkout. The primary checkout is shared ground. Two agents editing it at the same time lose each other's work: one stages the other's files, or checks the branch out from under them mid-task. This has happened repeatedly.

Check before your first edit. The branch reported at session start is a snapshot and goes stale:

git rev-parse --abbrev-ref HEAD    # the live branch
git status --short                 # files you never touched mean someone else is here
for p in $(pgrep -x claude); do lsof -a -p $p -d cwd -Fn 2>/dev/null | sed -n 's/^n//p'; done | sort | uniq -c

Then take a worktree. Use the native EnterWorktree tool if your harness has one, otherwise:

git fetch origin
git worktree add .claude/worktrees/<slug> -b <branch> origin/main
cp -R .zed .claude/worktrees/<slug>/.zed   # gitignored, so a fresh worktree comes up bare

Worktrees live under .claude/worktrees/ (gitignored), never as siblings of the checkout. Branch off origin/main, not local main, which may be stale or may belong to another agent. A stacked local branch is often already upstream as a squash merge, so origin/main is the right base even when local commits look unmerged.

Exceptions. Read-only work needs no worktree. Neither does a single edit you will commit within the minute, provided git status is clean and no other agent is live here. Everything else gets a worktree.

Architecture

• Roda
• SQLite with Sequel
• Puma
• Rufus scheduler
• Foreman
• Cloudflare CDN

Project Structure

lib/
├── app.rb                       # Main Roda app — mounts v1 and v2
├── base_conversion.rb           # Rebases rates from any base to a common base
├── blend_parity.rb              # Parity harness: replays query shapes through table and live paths
├── blended_rate.rb              # BlendedRate model: materialized pivot-frame blend, refresh/rebuild
├── blender.rb                   # Blends multi-provider rates: rebase → consensus → weighted average
├── bucket.rb                    # Shared SQL bucket expressions for weekly/monthly aggregation
├── cache.rb                     # Cloudflare cache purge, debounced with a trailing edge
├── carry_forward.rb             # Carries forward most recent provider rate within a lookback window
├── consensus.rb                 # Cross-provider outlier detection (MAD-based)
├── currency.rb                  # Currency model (materialized from rates)
├── currency_coverage.rb         # CurrencyCoverage model (provider-currency join)
├── defunct_currency.rb          # Defunct-currency registry: terminal dates for retired/redenominated ISO codes
├── db.rb                        # Database configuration
├── currency_patches.rb          # Patches Money::Currency: registers historical codes, fixes mangled names
├── log.rb                       # Shared logger
├── monthly_rate.rb              # MonthlyRate model on monthly_rates rollup table
├── no_store_on_error.rb         # Rack middleware: stops CDNs/caches from holding error responses
├── peg.rb                       # Currency peg definitions (from db/seeds/pegs/*.json)
├── peg_anchor.rb                # Peg-aware post-processing: substitutes peg rates, synthesises uncovered pegged quotes
├── provider.rb                  # Provider model: identity, backfill
├── provider/
│   ├── adapters/
│   │   ├── adapter.rb           # Abstract adapter: fetch interface, chunked iteration
│   │   └── <key>.rb             # One adapter per provider (auto-discovered)
│   └── adapters.rb              # Auto-requires all adapters
├── rate.rb                      # Rate model on rates table
├── rate_precision.rb            # Ingest-precision policy: strips binary float noise from synthesized rates
├── rate_scopes.rb               # Shared dataset scopes for rate tables (rates, weekly, monthly)
├── rate_validation.rb           # Ingest-validation policy: drops invalid rows on ingest, purges stored ones
├── roundable.rb                 # Currency-aware decimal rounding
├── weekly_rate.rb               # WeeklyRate model on weekly_rates rollup table
├── weighted_average.rb          # Recency-weighted averaging with exponential decay
├── versions/
│   ├── v1.rb                    # Legacy API (ECB-only, frozen)
│   ├── v1/                      # V1 internals (quotes, query, currency names)
│   ├── v2.rb                    # Multi-provider API
│   └── v2/
│       └── rate_query.rb        # V2 rate query builder (blending, filtering)
├── public/
│   ├── favicon.ico              # Served as a static file
│   ├── robots.txt               # Served as a static file
│   ├── v1/openapi.json          # V1 OpenAPI spec
│   └── v2/openapi.json          # V2 OpenAPI spec
└── tasks/
    ├── blend.rake               # Rebuild/verify the materialized blend
    ├── cache.rake               # Manual CDN purge
    ├── consensus.rake           # Consensus scan across providers
    ├── db.rake                  # Database migrations and setup
    ├── default.rake             # Default task (lint + test)
    ├── providers.rake           # Dynamic backfill task for all providers
    ├── rollups.rake             # Rebuild weekly/monthly rollup tables
    ├── rubocop.rake             # Linter task
    └── test.rake                # Test suite task

spec/                            # Minitest test suite
db/migrate/                      # Sequel migrations
db/seeds/
    ├── currency_patches.json    # Money::Currency patches (historical codes, name fixes)
    ├── defunct_currencies.json  # Defunct currencies: terminal dates for retired/redenominated ISO codes
    ├── pegs/                    # One JSON file per peg (e.g. aed.json, bam.json)
    └── providers/               # One JSON file per provider (e.g. ecb.json, boi.json)