# Fallback Screens Module

The Fallback Screens module owns route-level and reusable fallback pages in the admin app. It currently provides HTTP-style error screens for forbidden, not found, and server error states, and it is the intended home for future fallback pages such as maintenance, unavailable, empty-state, or generic recovery screens.

## Source Map

| Area                  | Path                                                         |
| --------------------- | ------------------------------------------------------------ |
| Frontend module       | `apps/admin/src/core/FallbackScreens/`                       |
| Frontend routes       | `apps/admin/src/core/FallbackScreens/config/routing.tsx`     |
| Frontend translations | `apps/admin/src/core/FallbackScreens/config/translation/`    |
| Frontend layout       | `apps/admin/src/core/FallbackScreens/view/layouts/`          |
| Backend module        | Not applicable. Fallback Screens is currently frontend-only. |

## Documentation

| Page                      | Purpose                                                           |
| ------------------------- | ----------------------------------------------------------------- |
| [Frontend](./frontend.md) | Routes, page structure, translations, ownership, and conventions. |
| [Backend](./backend.md)   | Backend ownership notes and when a backend change may be needed.  |

## Main Capabilities

- Render full-page fallback screens under `/error/*`.
- Provide reusable fallback page components for other core modules.
- Keep fallback screen translations module-local.
- Provide a consistent layout for fallback pages.
- Preserve stable public fallback URLs such as `/error/403`, `/error/404`, and `/error/500`.

## Ownership Rules

- FallbackScreens owns fallback page UI, fallback routing, and fallback-specific translations.
- Other modules may import reusable fallback pages, for example permission gates using `Error403Page`.
- Shared API/query error parsing does not belong here; keep it in shared error/query utilities.
- Domain-specific empty states should stay in the owning domain module unless they are generic enough to reuse across modules.
- Backend modules own the actual API status codes and response payloads. FallbackScreens only decides how the admin frontend presents fallback states.

## Common Change Guide

| Change                         | Start Here                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------ |
| Add a new fallback route       | `apps/admin/src/core/FallbackScreens/config/routing.tsx`                       |
| Add a new fallback page        | `apps/admin/src/core/FallbackScreens/pages/`                                   |
| Change fallback page layout    | `apps/admin/src/core/FallbackScreens/view/layouts/FallbackScreensLayout.tsx`   |
| Change translations            | `apps/admin/src/core/FallbackScreens/config/translation/en.json` and `uk.json` |
| Reuse a fallback in a module   | Export it from `apps/admin/src/core/FallbackScreens/index.ts`                  |
| Change global fallback routing | `apps/admin/src/app/routing/app_routing_setup.tsx`                             |