zero-fucks-given/docs/architecture/react-frontend/layers/refdata.md

Reference Data Layer

App-wide API-backed lookup datasets reused across modules — countries, languages, currencies, time zones, common option dictionaries. The layer fetches them, exposes reusable query hooks, and owns their cache keys.

Small dataset → one file; larger → a folder:

refdata/
├── countries.ts
├── languages.ts
└── currencies/
    ├── api.ts
    ├── dto.ts
    ├── mapper.ts
    ├── queries.ts
    └── keys.ts

Rules

1. App-wide datasets only — a dataset owned by one feature belongs in that module's data/ layer.
2. May use #infrastructure/axios and #infrastructure/reactQuery; must not import from view/, pages/, or feature modules.
3. Expose hooks or small service functions — consumers should not know endpoints or cache keys.
4. Add mappers when backend DTOs differ from app-facing data, tested like module data mappers.

Example

import { keepPreviousData, useQuery } from "@tanstack/react-query";
import { axiosClient } from "#infrastructure/axios";
import { createKeyBuilder } from "#infrastructure/reactQuery";

export const countriesCacheKey = createKeyBuilder(
  "REF_DATA",
  "COUNTRIES",
  "LIST",
);

interface CountryData {
  code: string;
  name: string;
}

export const useCountries = () => {
  return useQuery({
    queryKey: countriesCacheKey.store(),
    placeholderData: keepPreviousData,
    queryFn: async () => {
      return axiosClient
        .get<Array<CountryData>>("/datasets/countries")
        .then((data) => data.data);
    },
  });
};