# moov-io/fed architecture

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

- Interactive diagram: https://gitdiagram.com/moov-io/fed
- Repository: https://github.com/moov-io/fed

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration & Ingestion Layer
    subgraph "Configuration & Ingestion"
        cfg["Configuration & Env Loader\n(const.go, version.go\ncmd/server/main.go)"]:::ingest
        dl["Downloader\n(pkg/download/download.go)"]:::ingest
        prs["Parsers\n(normalize.go,\nACHDictionary.go,\nWIREDictionary.go,\nvalidators.go)"]:::ingest
    end

    %% Core Service & Repository Layer
    repo["In-Memory Repository\n(cmd/server/reader.go,\nreader_test.go)"]:::core
    sv["SearchService\n(cmd/server/search.go,\nsearch_test.go)"]:::core

    %% API & CLI Layer
    subgraph "API & CLI"
        api["HTTP API\n(cmd/server/http.go,\nsearch_handlers.go,\nsearch_handlers_test.go)"]:::api
        cli["CLI fedtest\n(cmd/fedtest/main.go,\nach.go, wire.go)"]:::api
        client["Generated Go Client\n(openapi.yaml,\napi/client.yaml,\nclient/)"]:::api
    end

    %% External Systems
    frb["FRB eServices"]:::external
    prom["Prometheus"]:::external

    %% Data Ingestion Flow
    cfg -->|"env vars"| dl
    dl -->|"plaintext/JSON"| prs
    prs -->|"index data"| repo

    %% Runtime Request Flow
    sv -->|"query repo"| repo
    api -->|"HTTP/REST"| sv
    cli -->|"Service API call"| sv
    client -->|"HTTP/REST"| api

    %% External interactions
    dl -->|"HTTP download"| frb
    api -->|"scrape /metrics"| prom

    %% Click Events
    click cfg "https://github.com/moov-io/fed/blob/master/cmd/server/main.go"
    click dl "https://github.com/moov-io/fed/blob/master/pkg/download/download.go"
    click prs "https://github.com/moov-io/fed/blob/master/normalize.go"
    click repo "https://github.com/moov-io/fed/blob/master/cmd/server/reader.go"
    click sv "https://github.com/moov-io/fed/blob/master/cmd/server/search.go"
    click api "https://github.com/moov-io/fed/blob/master/cmd/server/http.go"
    click cli "https://github.com/moov-io/fed/blob/master/cmd/fedtest/main.go"
    click client "https://github.com/moov-io/fed/blob/master/openapi.yaml"

    %% Styling
    classDef ingest fill:#0074D9,stroke:#001f3f,color:#ffffff
    classDef core fill:#2ECC40,stroke:#228B22,color:#000000
    classDef api fill:#FF851B,stroke:#FF4500,color:#000000
    classDef external fill:#AAAAAA,stroke:#666666,color:#000000
```
