107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
# Infrastructure Layer
|
|
|
|
## Table of Contents
|
|
|
|
- [Purpose](#purpose)
|
|
- [Responsibilities](#responsibilities)
|
|
- [Recommended Structure](#recommended-structure)
|
|
- [Rules](#rules)
|
|
- [Examples](#examples)
|
|
|
|
## Purpose
|
|
|
|
The `infrastructure/` layer contains app-wide technical adapters and integration helpers.
|
|
|
|
Use this layer for code that connects the frontend application to technical systems or shared runtime services, not for feature-specific business logic.
|
|
|
|
## Responsibilities
|
|
|
|
The `infrastructure/` layer is responsible for:
|
|
|
|
- HTTP clients and request/response interceptors
|
|
- React Query shared helpers, response types, query key helpers, and error normalization
|
|
- storage, browser, or runtime adapters
|
|
- shared formatting/service adapters such as date or name formatting services
|
|
- app-wide technical configuration wrappers
|
|
|
|
## Recommended Structure
|
|
|
|
```plaintext
|
|
infrastructure/
|
|
├── axios/
|
|
│ ├── index.ts # configured axios client
|
|
│ ├── interceptors.ts # request/response interceptors
|
|
│ └── axios.d.ts # axios type augmentation
|
|
│
|
|
├── reactQuery/
|
|
│ ├── index.ts
|
|
│ ├── errors.ts # query error handling helpers
|
|
│ ├── helpers.ts # query key and pagination helpers
|
|
│ ├── queryParams.ts # table/query-param mapping helpers
|
|
│ └── types.ts # shared API response/query types
|
|
│
|
|
├── IntlDate.ts # date formatting service adapter
|
|
└── IntlName.ts # name formatting service adapter
|
|
```
|
|
|
|
## Rules
|
|
|
|
1. Keep infrastructure feature-agnostic.
|
|
|
|
- No module-specific business rules
|
|
- No page or component composition
|
|
- No entity mapping that belongs in a module `data/mapper`
|
|
|
|
2. API modules should use infrastructure clients instead of creating their own clients.
|
|
|
|
```ts
|
|
import { axiosClient } from "#infrastructure/axios";
|
|
```
|
|
|
|
3. React Query helpers that are shared across modules belong here.
|
|
|
|
Examples: query key builders, list response types, pagination helpers, error extraction helpers.
|
|
|
|
4. UI layers must not call raw HTTP clients directly.
|
|
|
|
View and page code should call data-layer hooks. Direct `#infrastructure/axios` usage belongs in API/data modules, not in components.
|
|
|
|
5. Generic formatting adapters may be consumed by UI when they are not tied to a feature.
|
|
|
|
Examples: `IntlDate`, `IntlName`.
|
|
|
|
6. Prefer dependency injection for app-state coupling.
|
|
|
|
If an interceptor needs auth or query-client behavior, keep that coupling narrow and documented. Avoid importing random feature modules into infrastructure.
|
|
|
|
## Examples
|
|
|
|
API modules use the configured HTTP client:
|
|
|
|
```ts
|
|
import { axiosClient } from "#infrastructure/axios";
|
|
|
|
export class UserAPI {
|
|
getDetailed(id: number) {
|
|
return axiosClient.get(`/users/${id}`).then((response) => response.data);
|
|
}
|
|
}
|
|
```
|
|
|
|
Data/query modules use shared query helpers:
|
|
|
|
```ts
|
|
import {
|
|
createKeyBuilder,
|
|
getPaginationInfo,
|
|
} from "#infrastructure/reactQuery";
|
|
|
|
export const usersCacheKey = createKeyBuilder("USERS", "LIST");
|
|
```
|
|
|
|
UI can consume generic app-wide formatters:
|
|
|
|
```ts
|
|
import { IntlDate } from "#infrastructure/IntlDate";
|
|
```
|