How moov-io/fed works
Project type and purpose
• This is a Go-based microservice and library (“fed”) providing an HTTP API, command-line utilities, and a Go module for searching Federal Reserve ACH and Wire routing data.
• It ingests plaintext/JSON files (or downloads them from FRB eServices), builds in-memory indexes, and serves search endpoints (/fed/ach/search, /fed/wire/search). It also emits Prometheus metrics and ships an OpenAPI spec with a generated Go client.
File structure analysis
• cmd/
• server: HTTP server entrypoint (main.go, handlers, reader, search logic/tests)
• fedtest: CLI for running sample Fed ACH/Wire queries
• api/ & openapi.yaml
• raw OpenAPI spec (api/client.yaml, openapi-generator)
• client/: generated Go client code + docs (based on the spec)
• pkg/download: file-download logic (FRB API integration)
• core code at root:
• ACHDictionary.go, WIREDictionary.go, normalize.go, validators.go – parsing & modeling
• const.go, version.go – configuration, versioning
• data/: static sample data files (plaintext & JSON)
• Dockerfile(s), docker-compose.yml – containerization
• docs/: website for user/developer guides
• tests interspersed in each package
Key components to illustrate
a. Configuration & Env Loader
• Reads FEDACH_DATA_PATH, FEDWIRE_DATA_PATH, download credentials, HTTP bind addresses.
b. Data Ingestion
• FileSources: Local FS or FRB eServices downloader (pkg/download) → raw data files
• Parsers: plaintext (normalize.go) & JSON parsers → build in-memory dictionaries (ACHDictionary, WIREDictionary)
c. In-Memory Repository
• Indexed structures for fast routingNumber lookup
d. Service Layer
• SearchService: business logic to query the in-memory repositories
e. HTTP API Layer
• Handlers (cmd/server/search_handlers.go): parse HTTP requests → call SearchService → marshal JSON response
• Admin metrics (/metrics) for Prometheus
f. CLI Layer
• fedtest CLI: uses the same Service API or generated OpenAPI client to perform queries
g. OpenAPI / Client Generation
• openapi.yaml → openapi-generator → client/ package: reusable SDK
Relationships and data flows
• Startup:
[Config Loader] → [Downloader] → [Parsers] → [In‐Memory Repository]
• Serving requests:
Client HTTP or CLI → [HTTP Handler] → [Service Layer] → [Repository] → Response → HTTP or CLI Output
• External services: FRB eServices endpoint (for downloads), Prometheus (scrapes /metrics)
Architectural patterns & principles
• Layered architecture (Configuration → Ingestion → Service → API)
• Single responsibility: download, parse, search, serve
• In-memory data for low latency, no persistence beyond process lifetime
• OpenAPI-first design for generating clients and docs
• Containerized microservice with health/metrics endpoints
Putting it all together
[Environment & Config] → [Data Ingestion (pkg/download)] → [Parsers (ACHDictionary, WIREDictionary)] → [In-Memory Repository]
Then, at runtime:
[CLI fedtest] ──┐
↓
[HTTP API: cmd/server] → [Service Layer: search.go] → [Repository]
↑
[Generated Go client]
→ also show Prometheus scraping /metrics and FRB eServices as external nodes.
• Annotations for protocols (HTTP/REST, JSON, plaintext, CLI)