TASKS-1823 WebManager module

docs/core/permission/frontend.md

@@ -0,0 +1,98 @@
+# Permission Frontend
+
+The frontend module provides reusable permission-checking primitives for the admin app.
+
+Source: `apps/admin/src/core/Permission/`
+
+## Directory Structure
+
+```txt
+Permission/
+  config/        Static module config and messages.
+  entities/      Permission types.
+  hooks/         Current-user permission hook.
+  lib/           Pure permission check function.
+  view/gates/    React gate components.
+```
+
+## Types
+
+Permission types live in:
+
+```txt
+entities/permission.ts
+```
+
+Key concepts:
+
+```ts
+type PermissionCheckMode = "all" | "any";
+type RequiredPermissions = string | string[];
+```
+
+## Hook
+
+Current-user permission access:
+
+```txt
+hooks/usePermissions.ts
+```
+
+The hook reads auth state from AuthProvider and returns:
+
+```ts
+permissions;
+isAdmin;
+loading;
+```
+
+`isAdmin` is based on the configured super admin id.
+
+## Pure Permission Check
+
+Permission check logic:
+
+```txt
+lib/hasPermission.ts
+```
+
+Behavior:
+
+- Super admin passes all checks.
+- `all` mode requires every permission.
+- `any` mode requires at least one permission.
+- Empty required permissions should be treated carefully at call sites.
+
+## Gates
+
+### `PermissionGate`
+
+Use for conditional UI controls such as buttons and menu items.
+
+```tsx
+<PermissionGate requiredPermissions="admins.update">
+  <Button>Edit</Button>
+</PermissionGate>
+```
+
+### `PermissionPageGate`
+
+Use for route-level access protection.
+
+```tsx
+<PermissionPageGate requiredPermissions={["admins.view", "role.view"]}>
+  <AdminListPage />
+</PermissionPageGate>
+```
+
+If access is denied, it renders the provided fallback or a 403 page.
+
+## Translations
+
+The module has a local message bundle for consistency:
+
+```txt
+config/messages.ts
+config/translation/en.json
+config/translation/uk.json
+```