If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/fixerAPI/fixer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live fixerAPI/fixer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/fixerAPI/fixer.

What it runs against: a local clone of fixerAPI/fixer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in fixerAPI/fixer | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1375 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of fixerAPI/fixer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/fixerAPI/fixer.git
#   cd fixer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of fixerAPI/fixer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "fixerAPI/fixer(\\.git)?\\b" \\
  && ok "origin remote is fixerAPI/fixer" \\
  || miss "origin remote is not fixerAPI/fixer (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app/lib/api.rb" \\
  && ok "app/lib/api.rb" \\
  || miss "missing critical file: app/lib/api.rb"
test -f "app/lib/bank.rb" \\
  && ok "app/lib/bank.rb" \\
  || miss "missing critical file: app/lib/bank.rb"
test -f "app/lib/quote.rb" \\
  && ok "app/lib/quote.rb" \\
  || miss "missing critical file: app/lib/quote.rb"
test -f "app/config/environment.rb" \\
  && ok "app/config/environment.rb" \\
  || miss "missing critical file: app/config/environment.rb"
test -f "app/lib/tasks/rates.rake" \\
  && ok "app/lib/tasks/rates.rake" \\
  || miss "missing critical file: app/lib/tasks/rates.rake"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1375 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1345d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/fixerAPI/fixer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Fixer is a Ruby-based foreign exchange rates API server that provides real-time and historical currency conversion data via HTTP endpoints. It aggregates exchange rate data from 16+ sources (superseding the legacy European Central Bank-only approach), supports 170+ currencies, and exposes a REST API at /api/latest and /api/historical endpoints. The codebase includes both the server application (in app/) and a published Ruby gem client library (in gem/) for consuming the API. Dual-package structure: app/ contains the Sinatra-based server with request handlers in app/lib/api.rb, domain logic split into app/lib/bank.rb (rate fetching), app/lib/currency.rb, and app/lib/quote.rb (conversions). Database layer uses Sequel ORM (app/config/initializers/sequel.rb) with migrations in app/db/migrate/. The gem/ folder is a standalone published library wrapping API calls for Ruby clients.

Backend developers and financial/fintech applications that need current and historical FX rates without building their own data pipeline. API consumers use the gem (gem/lib/fixer.rb) or HTTP calls; server maintainers deploy the Rails-like app (Sinatra-based via app/lib/api.rb) to provide the service.

Production-ready with moderate age signals: CI via Travis CI (.travis.yml), Docker containerization (app/Dockerfile, docker-compose.yml), a published gem with versioning (gem/lib/fixer/version.rb), and comprehensive test coverage (app/spec/ with API, bank, currency, quote, and edge case specs). The README indicates a major v2 relaunch in March 2018, suggesting active maintenance, though commit recency is not visible in the provided data.

Moderate risk: the legacy API (api.fixer.io) was deprecated in March 2018 and users must migrate to the new endpoint, creating potential breakage for old integrations. The codebase is heavily tied to external data sources (16+ providers) which are not version-pinned in the visible Gemfile; a single provider outage or rate-limit could degrade service. Single-maintainer risk is unknown from the data provided.

The repo reflects a post-v2-relaunch state (March 2018+): the major work was migrating from the legacy api.fixer.io to data.fixer.io/api with access key auth. Current activity is likely maintenance and data source synchronization via app/lib/tasks/rates.rake (which updates currency rates) and app/bin/schedule (scheduled job runner).

Clone and install dependencies: git clone https://github.com/fixerAPI/fixer.git && cd app && bundle install. Set up environment from .env.example (copy to .env and add FIXER_ACCESS_KEY). Start via Docker: docker-compose up, or locally with Unicorn: bundle exec unicorn -c config/unicorn.rb. Migrate the database: bundle exec rake db:migrate.

Daily commands: Development: cd app && bundle install && bundle exec unicorn -c config/unicorn.rb (runs on port inferred from config/unicorn.rb). Docker: docker-compose up (uses docker-compose.yml and docker-compose.override.yml for dev, docker-compose.prod.yml for production). Scheduled jobs: bundle exec ./bin/schedule (runs background rate-fetching tasks).

• app/lib/api.rb — Main API endpoint handler that processes currency conversion requests and rate queries; every change to API behavior flows through this entry point.
• app/lib/bank.rb — Core exchange rate calculation and currency conversion logic; implements the heart of the FX computation engine.
• app/lib/quote.rb — Quote model that represents exchange rate data and manages rate caching/retrieval; critical for performance.
• app/config/environment.rb — Loads all dependencies and initializes the Sinatra app; must be understood before running or modifying the application.
• app/lib/tasks/rates.rake — Rake task that fetches and updates currency rates from external sources; the scheduled job that keeps rates fresh.
• app/db/migrate/001_create_currencies.rb — Database schema for storing currency metadata; any schema changes impact the entire data layer.
• gem/lib/fixer.rb — Public Ruby gem interface for the Fixer API; the main client library that external developers use.

Add a New Currency Exchange Endpoint

1. Define the HTTP route handler in app/lib/api.rb to accept base and target currencies as params (app/lib/api.rb)
2. Call Bank.convert(from, to, amount) to perform the conversion calculation (app/lib/bank.rb)
3. Return JSON response with quote data using Quote.fetch(from, to) (app/lib/quote.rb)
4. Add test case to app/spec/api_spec.rb covering success and error paths (app/spec/api_spec.rb)

Integrate a New Exchange Rate Data Source

1. Create a new provider class in app/lib/ that fetches rates from the external API (app/lib/bank.rb)
2. Update the rates.rake task to call your provider's fetch method and store rates in database (app/lib/tasks/rates.rake)
3. Modify Quote.fetch() to query the newly populated rate data (app/lib/quote.rb)
4. Test with real rate data in app/spec/quote_spec.rb using VCR cassettes (app/spec/quote_spec.rb)

Deploy to Production with Docker

1. Set production environment variables in .env or deployment platform (API keys, database URL, etc.) (.env.example)
2. Use docker-compose.prod.yml to build and run the containerized app with proper networking (docker-compose.prod.yml)
3. Configure Unicorn webserver settings in app/config/unicorn.rb for worker processes (app/config/unicorn.rb)
4. Run database migrations using app/lib/tasks/db.rake inside the container (app/lib/tasks/db.rake)

Publish an Update to the Ruby Gem

1. Update the version number in gem/lib/fixer/version.rb (gem/lib/fixer/version.rb)
2. Modify client behavior in gem/lib/fixer/feed.rb (HTTP communication, parsing, etc.) (gem/lib/fixer/feed.rb)
3. Add test coverage in gem/spec/fixer_spec.rb or gem/spec/fixer/feed_spec.rb (gem/spec/fixer_spec.rb)
4. Update gem/fixer.gemspec with new version and dependencies, then run gem build and push to RubyGems (gem/fixer.gemspec)

• Ruby + Sinatra — Lightweight and fast REST API framework; good for simple request-response patterns with minimal overhead.
• Sequel ORM — Provides database abstraction and query builder; maintains data integrity and supports migrations.
• PostgreSQL (inferred) — Reliable relational database for storing currency metadata and historical rates; ACID compliance ensures data accuracy.
• Docker & Docker Compose — Containerization ensures reproducible deployments across development, staging, and production environments.
• Unicorn Application Server — Production-grade Ruby app server with process preforking; handles multiple concurrent requests efficiently.
• Rake Tasks & Scheduler — Enables background job execution for periodic rate updates without blocking API requests.

• In-memory rate caching at application level (Quote model) rather than distributed cache (Redis/Memcached)

  • Why: Simpler deployment footprint and reduced operational complexity for small-to-medium traffic; no external service dependency.
  • Consequence: Cache is per-process; multi-worker setup has stale or inconsistent rate data across processes. Requires coordinated cache invalidation on rate updates.

• Rake tasks with external scheduler (cron, Kubernetes CronJob) instead of built-in job queue (Sidekiq, Resque)

  • Why: Minimal external dependencies; easy to understand and debug for small team.
  • Consequence: No built-in retry logic, no job monitoring UI, and no guaranteed exactly-once execution if scheduler restarts during job run.

• Monolithic app structure (web server + rate updater in same codebase) rather than microservices

  • Why: Single deployment unit simplifies DevOps; shared database avoids eventual consistency issues.
  • Consequence: Scaling one concern (e.g., API throughput) requires scaling the entire service; coupling makes independent deployment harder.

• Public Ruby gem (gem/) separate from API server (app/) in same repository

  • Why: Keeps client library and server implementation aligned; shared test patterns.
  • Consequence: Requires careful versioning to avoid tight coupling; gem and API may drift if not coordinated.

• Does not provide real-time streaming of rate changes; data is updated on a scheduled interval (typically hourly).
• Does not support authentication or per-user rate limits; assumes API key-based access is handled by reverse proxy or API gateway.
• Does not handle multi-currency wallets or transaction settlement; only provides exchange rates and simple conversions.
• Not designed for high-frequency trading or low-latency requirements; ~1-2s end-to-end latency is typical.

1. Access Key Required: API calls must include access_key parameter (see .env.example); legacy api.fixer.io URLs will fail. 2. Free Plan Limits: EUR-only as base currency and 1000 requests/month for free accounts; code may not validate this. 3. Data Source Coupling: External rate providers (16+) are not abstracted behind a versioned interface; provider API changes can break the bank.rb fetcher. 4. Database Migrations: Sequel migrations are hand-rolled; no automatic rollback safety. 5. Scheduled Job Timing: The bin/schedule runner and rates.rake timing are not visible; unclear what the update frequency is (README says 'every hour, 10-minutes, or every minute' depending on plan, but code doesn't reflect tiers). 6. Docker Service Dependencies: docker-compose.yml likely depends on a database service being ready; bin/wait-for-it.sh suggests startup sequencing issues.

• Foreign exchange arbitrage and rate consistency — Fixer aggregates 16+ data sources with different update frequencies; understanding how to handle rate mismatches, stale data, and triangulation errors is core to reliable currency conversion.
• Sequel ORM lazy loading and query optimization — The app/lib/bank.rb and other domain classes use Sequel to fetch currency and rate data; understanding N+1 queries and eager loading is essential to avoid performance regressions when adding new API endpoints.
• Rate limiting and quota enforcement (free vs paid tiers) — The README mentions free accounts have 1000 requests/month and EUR-only access; the API must track usage and enforce these limits in app/lib/api.rb, but enforcement logic is not visible in the provided files.
• Decimal precision in financial calculations — Currency conversion in app/lib/quote.rb must handle rounding and precision without floating-point errors; this is non-obvious in Ruby and critical for correctness (e.g., converting 1.005 EUR to GBP must not lose cents).
• Scheduled task management and idempotency — The bin/schedule runner and app/lib/tasks/rates.rake update exchange rates on a schedule; understanding cron-like scheduling, task deduplication, and failure recovery prevents duplicate or missed updates.
• API deprecation and versioning strategy — Fixer migrated from api.fixer.io to data.fixer.io/api in March 2018; understanding how to version endpoints, manage breaking changes, and communicate deprecation is essential for adding new features without breaking existing clients.
• Multi-provider data aggregation and fallback strategies — With 16+ data sources, the system must handle provider outages, rate disagreements, and partial failures; the design pattern used in app/lib/bank.rb (if any) determines resilience.

• exchangerate-api/exchangerate-api — Alternative FX rate API service with similar REST endpoint structure; useful for comparing API design and feature parity.
• openexchangerates/openexchangerates — Established competitor providing real-time FX data; reference for market-standard features and pricing models.
• currencyapi-com/currencyapi-ruby — Ruby client library for another FX provider; useful reference for client gem patterns and error handling.
• ruby-bank/money — Popular Ruby library for handling currency objects and conversions; used alongside or instead of this API for in-app calculations.
• fixerAPI/docker-setup — Likely companion repo containing deployment manifests and infrastructure-as-code for Fixer; needed for running this repo in production.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Bank class currency conversion pipeline

The app/lib/bank.rb file handles core currency conversion logic but app/spec/bank_spec.rb lacks comprehensive tests for edge cases in multi-currency conversions, especially around decimal precision and historical rate lookups. Given this is a financial API, robust banking operation tests are critical to prevent rounding errors and rate inconsistencies that could affect thousands of users.

• [ ] Review app/lib/bank.rb to identify untested conversion scenarios (especially bid/ask spreads, edge currencies, zero amounts)
• [ ] Enhance app/spec/bank_spec.rb with tests for: decimal precision (>2 places), missing rates, rate staleness, concurrent conversion requests
• [ ] Add test fixtures in app/spec/helper.rb for historical rate data from app/db/migrate/001_create_currencies.rb schema
• [ ] Ensure all tests reference real currency pairs and validate against actual Fixer API rate behavior

Migrate legacy API endpoint tests to verify backward compatibility layer

The README prominently mentions deprecation of api.fixer.io (March 6, 2018) and migration to data.fixer.io. However, app/spec/api_spec.rb doesn't show explicit tests validating the compatibility shim or error responses for legacy access tokens. Without these tests, breaking changes to deprecated endpoints could slip through CI.

• [ ] Examine app/lib/api.rb to identify all deprecated endpoint handlers and legacy token validation logic
• [ ] Add dedicated test suite in app/spec/api_spec.rb for: legacy token rejection with proper 401 codes, endpoint deprecation warnings, redirect handling if applicable
• [ ] Document expected behavior for deprecated routes in README.md with example requests/responses
• [ ] Run tests against both docker-compose.yml (dev) and docker-compose.prod.yml to ensure deprecation layer works in production

Add comprehensive rate fetching and caching tests for Quote class with stale data scenarios

app/lib/quote.rb likely handles rate data retrieval and caching, but app/spec/quote_spec.rb doesn't appear to test critical failure modes: missing rates, cache invalidation timing (important given the app/lib/tasks/rates.rake scheduled task), and fallback behavior. Incomplete tests here could lead to stale rates being served to users without their knowledge.

• [ ] Review app/lib/quote.rb and app/lib/tasks/rates.rake to understand the rate refresh schedule and cache TTL strategy
• [ ] Add tests to app/spec/quote_spec.rb for: cache hits/misses, stale rate detection, database query fallback (schema in app/db/migrate/001_create_currencies.rb), timeout handling
• [ ] Mock external rate source failures and verify graceful degradation (fallback to cached rates with warnings)
• [ ] Test the Sequel database integration in app/config/initializers/sequel.rb to ensure quotes correctly read from persisted currency records

• Add RSpec test coverage for app/lib/currency.rb: the file exists but no corresponding spec/currency_spec.rb is explicitly tested for symbol validation, name lookup, or edge cases like deprecated currencies. Write tests for currency creation, validation, and error handling.: Easy: Low-risk, self-contained, and improves code confidence.
• Document the data source architecture: create a README or code comment in app/lib/bank.rb explaining how the 16+ external providers are integrated, their update frequency, and failure-handling strategy. The README mentions multiple sources but the code structure is not documented.: Easy: Onboarding blocker for anyone touching rate-fetching; minimal code changes.
• Add a health-check endpoint to app/lib/api.rb (e.g., GET /health) that returns database and rate-cache status. Currently no way for load-balancers or monitoring to verify the service is functional.: Medium: Production-critical for deployment reliability; integrates with existing API structure.

• Critical · Hardcoded Database Credentials in Docker Compose — docker-compose.yml (web and scheduler services). The docker-compose.yml file contains hardcoded PostgreSQL credentials in the DATABASE_URL environment variable. The connection string 'postgres://postgres@db/postgres' uses the default 'postgres' user with no password, which is a significant security risk in production environments. Fix: Use Docker secrets or environment variables injected at runtime. Store credentials in a .env file (which should not be committed) and use docker-compose.override.yml for local development. For production, use Docker Swarm secrets or Kubernetes secrets.
• High · Missing Database Authentication — docker-compose.yml (db service). The PostgreSQL database in docker-compose.yml is exposed without any password authentication. The DATABASE_URL uses an empty password for the postgres user, allowing unauthorized access to the database. Fix: Set a strong password for the PostgreSQL user using POSTGRES_PASSWORD environment variable and update the DATABASE_URL connection string accordingly.
• High · Exposed Database Service to Web Container — docker-compose.yml (db links configuration). The docker-compose.yml uses deprecated 'links' directive to connect containers, which establishes direct network access. Combined with lack of credentials, this allows the web service unrestricted database access. Fix: Replace 'links' with explicit network configuration. Implement network segmentation and restrict database access. Use 'networks' directive instead of 'links'.
• High · Insecure Default Environment Configuration — .env.example. The .env.example file shows production environment configuration but lacks security headers and uses HTTPS_METHOD=noredirect which disables HTTPS enforcement. There is no indication of HSTS headers or other security best practices. Fix: Set HTTPS_METHOD=redirect to enforce HTTPS. Add security headers configuration (HSTS, CSP, X-Frame-Options, etc.). Use a proper secrets management system for production.
• Medium · Missing Dependency Information — app/Gemfile, gem/Gemfile. The Gemfile and Gemfile.lock files are not provided for static analysis. This prevents identification of known vulnerable gem dependencies that may be in use. Fix: Run 'bundle audit' regularly to identify vulnerable dependencies. Keep all gems updated to their latest secure versions. Implement dependency scanning in CI/CD pipeline.
• Medium · Exposed Container Port Without Rate Limiting Enforcement — docker-compose.yml (web service expose), limit_req.conf. The web service exposes port 8080, and while limit_req.conf exists, there's no evidence it's properly integrated into the application or nginx configuration for DDoS protection. Fix: Ensure limit_req.conf is properly loaded and configured in nginx/reverse proxy. Implement API rate limiting in the application layer as well. Verify rate limiting is enforced for all endpoints.
• Medium · No Input Validation Documentation Visible — app/lib/api.rb. As an API handling currency conversion and exchange rates, there's no visible input validation strategy in the file structure. API endpoints could be vulnerable to injection attacks or malformed input attacks. Fix: Implement comprehensive input validation for all API endpoints. Validate and sanitize all user inputs. Use parameterized queries or ORM protections against SQL injection (verify Sequel ORM is used correctly).
• Medium · Deprecated Travis CI Configuration — .travis.yml. The .travis.yml file is present but may contain outdated security practices. Travis CI has had security concerns and deprecation warnings in recent years. Fix: Migrate to modern CI/CD platforms (GitHub Actions, GitLab CI, etc.). Ensure encrypted secrets management. Review and update CI/CD security practices.
• Low · No CORS Configuration Visible — app/lib/api.rb or app/config/app.rb. As a public API for currency conversion, CORS headers should be explicitly configured. No visible CORS policy configuration is apparent in the file structure. Fix: Implement explicit CORS policy allowing only trusted domains. Use middleware to set appropriate Access-Control headers. Document CORS policy in API documentation.
• Low · undefined — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.