TASKS-1823 WebManager module

2026-08-28 08:35:58 +00:00
parent fdb2cf3837
commit c93d8c025b
654 changed files with 26232 additions and 6075 deletions
@@ -0,0 +1,47 @@
+# 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`                             |
@@ -0,0 +1,29 @@
+# Fallback Screens Backend
+
+Fallback Screens is currently a frontend-only core module.
+
+There is no backend source folder for this module.
+
+## Backend Relationship
+
+Backend modules may return HTTP status codes or API error payloads that eventually lead the admin frontend to show a fallback screen, but the fallback UI is owned by:
+
+```txt
+apps/admin/src/core/FallbackScreens/
+```
+
+Examples:
+
+| Status | Frontend fallback      | Notes                                         |
+| ------ | ---------------------- | --------------------------------------------- |
+| `403`  | `/error/403` or inline | Used for permission denied states.            |
+| `404`  | `/error/404`           | Used for unknown frontend routes.             |
+| `500`  | `/error/500`           | Used for generic server failure presentation. |
+
+## When Backend Changes Are Needed
+
+Backend changes are only needed when:
+
+- A backend endpoint should return a different status code.
+- A redirect or auth flow should navigate the frontend to a fallback route.
+- A feature needs a new machine-readable error contract that the frontend can map to a fallback screen.
@@ -0,0 +1,79 @@
+# Fallback Screens Frontend
+
+The frontend module provides fallback UI for app-level error and recovery states.
+
+Source: `apps/admin/src/core/FallbackScreens/`
+
+## Directory Structure
+
+```txt
+FallbackScreens/
+  config/        Routes, messages, and translations.
+  pages/         Route-level fallback pages.
+  view/
+    layouts/     Shared fallback page layout.
+```
+
+## Routes
+
+Frontend route config:
+
+```txt
+config/routing.tsx
+```
+
+Mounted route path:
+
+```txt
+/error/*
+```
+
+| Route        | Page           | Purpose                              |
+| ------------ | -------------- | ------------------------------------ |
+| `/error`     | `Error404Page` | Default fallback route.              |
+| `/error/403` | `Error403Page` | Forbidden or permission denied page. |
+| `/error/404` | `Error404Page` | Not found page.                      |
+| `/error/500` | `Error500Page` | Internal server error page.          |
+
+Unknown `/error/*` paths redirect to `/error/404`.
+
+## App Integration
+
+The app-level router mounts `fallbackScreensRoute` from:
+
+```txt
+apps/admin/src/app/routing/app_routing_setup.tsx
+```
+
+The app-level i18n config merges `fallbackScreensMessages` from:
+
+```txt
+apps/admin/src/app/i18n/config.ts
+```
+
+## Translations
+
+Translations are module-local:
+
+```txt
+config/messages.ts
+config/translation/en.json
+config/translation/uk.json
+```
+
+Use only `FALLBACK_SCREENS.*` keys inside this module.
+
+Do not put fallback page strings in app-level files such as:
+
+```txt
+apps/admin/src/app/i18n/messages/en.json
+apps/admin/src/app/i18n/messages/uk.json
+```
+
+## Page Conventions
+
+- Keep route-level fallback pages under `pages/*Page/index.tsx`.
+- Keep shared wrapper layout under `view/layouts/`.
+- Keep public URLs stable unless there is a migration plan.
+- Prefer module-local translation keys for all visible text, including generic-looking actions like return-home links.
+- Add a route only when the fallback is intended to be navigable. Inline-only reusable fallbacks can be exported without a route.