How mhannan-dev/symfony_acl works
1. Repository shape
- This is a decoupled two-app setup: api/ is a Symfony 6.4+ backend, and frontend/ is a standalone Nuxt 3/Vue 3 application.
- The primary architectural boundary is HTTP: the Nuxt app consumes the Symfony REST API rather than sharing server-side code.
2. Frontend as an admin console
- The Nuxt app is organized like a feature-based admin UI with route-driven pages for users, groups, permissions, content-types, activity-logs, dashboard, and login.
- layouts/admin.vue and layouts/default.vue separate authenticated admin screens from public/auth screens.
- middleware/auth.ts gates protected routes, so authentication is enforced at the client boundary as well as on the API.
3. Frontend state and API access
- plugins/vue-query.ts indicates server state is managed with Vue Query rather than ad hoc local fetch logic.
- layers/shared/composables/useApi.ts is the main client-side API abstraction, while layers/features/auth/composables/useAuth.ts centralizes authentication behavior.
- Shared UI components such as inputs, modal dialogs, and action buttons support consistent CRUD interactions across the admin screens.
4. Backend HTTP layer
- Symfony controllers are split into API controllers, versioned API controllers under Controller/Api/V1, and an Admin controller area.
- ApiResponseTrait suggests the backend standardizes JSON responses, likely to keep frontend consumption consistent.
- The versioned controller set (Auth, User, Group, Permission, ContentType, ActivityLog) forms the public contract consumed by the Nuxt app.
5. Backend domain model
- The core domain is a Django-style RBAC schema: User, Group, Permission, ContentType, plus join entities UserGroup, UserPermission, and GroupPermission.
- ActivityLog captures audit history, linking users and content types to recorded actions.
- ResetPasswordRequest supports password recovery flows.
6. Persistence and data access
- Doctrine ORM is the persistence layer, with migrations in api/migrations and seed data in AppFixtures.
- The presence of dedicated repositories for each entity indicates the app uses repository-backed queries rather than direct SQL or a generic service layer.
- This keeps persistence concerns isolated from controllers and authorization logic.
7. Authorization and permission evaluation
- Security/PermissionVoter.php and Service/PermissionCheckService.php are the main enforcement points for RBAC decisions.
- Command/SyncPermissionsCommand.php suggests permissions can be synchronized from code or metadata into the database, which is important for keeping the permission catalog aligned with the domain model.
- This is the key boundary where business authorization is separated from transport and persistence.
8. Request validation and DTO flow
- DTO/LoginRequest.php and DTO/ApiRequestInterface.php show the API uses request DTOs instead of binding directly to entities.
- ArgumentResolver/ApiRequestResolver.php bridges incoming HTTP requests to DTOs.
- ApiValidationException and its listener centralize validation error handling so bad input becomes a predictable API response.
9. Auth, reset password, and mail
- The backend includes Symfony security config plus a reset-password package and Twig email template, so authentication is not just API login but also account recovery.
- mailer.yaml and templates/reset_password/email.html.twig indicate outbound email is part of the operational flow.
- NelmioCors config matters because the frontend and backend run as separate apps in development.
10. Operational and local-dev structure
- compose.yaml / compose.override.yaml, .env, and Symfony console commands show the project is designed to run with explicit environment setup and database migrations.
- public/ contains the web entrypoint and a handful of diagnostic/utility scripts, but those are operational helpers rather than core domain logic.
- The app also includes a prebuilt frontend bundle under api/public/build, which suggests the backend can serve compiled assets in some deployment modes, though the main architecture remains split frontend/backend.
11. What an architecture diagram should emphasize
- Draw two main boxes: Nuxt UI and Symfony API.
- Inside the API box, show transport/controllers, validation DTOs, RBAC services/voters, repositories/entities, and supporting flows for login/reset-password/activity logging.
- Inside the frontend box, show routed pages, auth middleware, shared composables, and Vue Query-backed API access.
- The central data store is the relational database backing Doctrine entities; email is the other notable external dependency for password recovery.
Main entry points: pages Route pages · V1 V1 API · Entity Domain model · useApi.ts API composable
Components 22
Nuxt UI
Standalone Nuxt 3/Vue 3 admin client that consumes the API over HTTP.
- Route pages · Feature-driven admin screens for users, groups, permissions, content types, activity logs, dashboard, and login.
frontend/app/pages - Layouts · Separates authenticated admin screens from public/auth screens.
frontend/app/layouts - Auth middleware · Client-side protection for authenticated routes.
frontend/app/middleware/auth.ts - Vue Query · Server-state management and request lifecycle handling for the UI.
frontend/app/plugins/vue-query.ts - API composable · Shared client-side abstraction for calling the backend API.
frontend/layers/shared/composables/useApi.ts - Auth composable · Centralized frontend authentication behavior and session handling.
frontend/layers/features/auth/composables/useAuth.ts - Login form · Login entry point used by the public auth flow.
frontend/layers/features/auth/components/LoginForm.vue - Shared UI · Reusable inputs, buttons, and modal dialogs for CRUD workflows.
frontend/layers/shared/components
Symfony API
Symfony 6.4 backend exposing versioned REST endpoints, RBAC, and persistence.
- V1 API · Versioned public contract consumed by the Nuxt app.
api/src/Controller/Api/V1 - API controllers · Non-versioned JSON endpoints and shared API response handling.
api/src/Controller/Api - Admin area · Backend-admin controller surface for internal/admin operations.
api/src/Controller/Admin - Request DTOs · Typed request objects bridged from HTTP by a custom argument resolver.
api/src/DTO - Validation flow · Converts API validation failures into predictable JSON responses.
api/src/EventListener - RBAC layer · Permission evaluation and enforcement for users, groups, and permissions.
api/src/Security - Permission service · Encapsulates permission checks used by controllers and security rules.
api/src/Service/PermissionCheckService.php - Domain model · Users, groups, permissions, content types, activity logs, and reset-password records.
api/src/Entity - Repositories · Doctrine-backed query layer for each core entity.
api/src/Repository - Migrations · Database schema evolution for the Doctrine model.
api/migrations - Fixtures · Initial or sample data loaded into the database.
api/src/DataFixtures/AppFixtures.php - Reset email · Password-recovery email content rendered by Twig.
api/templates/reset_password/email.html.twig
External
Infrastructure dependencies used by the application.
- Database · Primary persistence for doctrine entities, RBAC data, and audit history.
- Mail system · Outbound delivery channel for password reset messages.
Connections 21
- Route pages → Layouts: uses · Route pages are wrapped by public or admin layouts.
- Route pages → Auth middleware: guarded by · Protected pages are gated by the auth middleware.
- Route pages → Vue Query: fetches via · Pages rely on Vue Query for server state and mutations.
- Route pages → API composable: calls · CRUD screens use the shared API abstraction.
- Login form → Auth composable: drives · The login form is wired to the auth composable.
- Auth composable → API composable: auth calls · Authentication behavior is implemented through API requests.
- Shared UI → Route pages: supports · Reusable controls support admin CRUD screens.
- API composable → V1 API: HTTP · The frontend consumes the versioned REST API.
- V1 API → Request DTOs: binds · Versioned controllers accept request DTOs.
- Request DTOs → Validation flow: errors to · Invalid DTO input is normalized into API validation responses.
- V1 API → Permission service: checks · Controllers consult permission logic for access control.
- Permission service → RBAC layer: enforced by · Service collaborates with the security layer for RBAC decisions.
- RBAC layer → Domain model: uses · Authorization decisions depend on users, groups, and permissions.
- API controllers → Repositories: queries · Non-versioned API controllers read and write through repositories.
- Admin area → Permission service: authorizes · Admin actions are protected by permission checks.
- Repositories → Domain model: persists · Repositories operate on Doctrine entities.
- Domain model → Database: stored in · The domain model is persisted in the relational database.
- Migrations → Database: evolves · Migrations define schema changes in the database.
- Fixtures → Database: seeds · Fixtures populate initial data.
- Reset email → Mail system: delivered via · Password reset email content is sent through the mail system.
- V1 API → Domain model: exposes · The public API surfaces core RBAC and audit entities.