# Access Control Module

The Access Control module manages admin accounts, roles, and permissions in the admin app. It is the UI boundary for deciding who can access which admin features.

## Source Map

| Area                      | Path                                                    |
| ------------------------- | ------------------------------------------------------- |
| Frontend module           | `apps/admin/src/core/AccessControl/`                    |
| Frontend routes           | `apps/admin/src/core/AccessControl/config/routing.tsx`  |
| Frontend translations     | `apps/admin/src/core/AccessControl/config/translation/` |
| Backend admin module      | `backend/app/base_modules/Admin/`                       |
| Backend role module       | `backend/app/base_modules/Role/`                        |
| Backend permission module | `backend/app/base_modules/Permission/`                  |
| Permission loader         | `backend/app/services/permission_service.ts`            |

## Documentation

| Page                      | Purpose                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------- |
| [Frontend](./frontend.md) | Routes, UI structure, data layer, forms, translations, and cache invalidation.        |
| [Backend](./backend.md)   | Admin, role, and permission API routes, policies, validators, and permission loading. |

## Main Capabilities

- List, search, sort, paginate, create, edit, and delete admin accounts.
- Assign roles to admin accounts.
- List, create, edit, and delete roles.
- Assign permissions to roles.
- Load available permission definitions from backend module permission configs.
- Gate access to screens and actions through the Permission core module.

## Ownership Rules

- AccessControl owns management UI for admins, roles, and role permissions.
- Backend Admin owns account persistence and profile update endpoint.
- Backend Role owns role persistence and role-permission sync.
- Backend Permission owns the available permission list endpoint.
- Permission core module owns permission checking and React gates.
- Auth core module owns the current authenticated admin and session state.

## Common Change Guide

| Change                      | Start Here                                                                                           |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| Add an admin field          | `entities/AdminEntity.ts`, `data/api/dto.ts`, `data/mappers/AdminMapper.ts`, `view/forms/AdminForm/` |
| Change admin list columns   | `view/widgets/AdminTable.tsx`                                                                        |
| Change role form behavior   | `view/forms/RoleForm/`                                                                               |
| Add a new permission source | Backend module `config/permissions.ts` and `backend/app/services/permission_service.ts`              |
| Change cache invalidation   | `data/queries/cache.ts`                                                                              |
| Change translations         | `config/translation/en.json` and `config/translation/uk.json`                                        |
| Change backend admin API    | `backend/app/base_modules/Admin/controller/admin_controller.ts`                                      |
| Change backend role API     | `backend/app/base_modules/Role/controller/role_controller.ts`                                        |