# mhannan-dev/symfony_acl architecture

> Architecture diagram of the GitHub repository mhannan-dev/symfony_acl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mhannan-dev/symfony_acl
- Repository: https://github.com/mhannan-dev/symfony_acl

## Overview

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: [`frontend/app/pages`](https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/app/pages) (Route pages), [`api/src/Controller/Api/V1`](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Api/V1) (V1 API), [`api/src/Entity`](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Entity) (Domain model), [`frontend/layers/shared/composables/useApi.ts`](https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/shared/composables/useApi.ts) (API composable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Nuxt UI"]
  node_frontend_pages["Route pages<br/>nuxt pages"]
  node_frontend_layouts["Layouts"]
  node_frontend_auth_mw["Auth middleware<br/>route guard<br/>[auth.ts]"]
  node_frontend_query["Vue Query<br/>state plugin<br/>[vue-query.ts]"]
  node_frontend_api["API composable<br/>http client<br/>[useApi.ts]"]
  node_frontend_auth["Auth composable<br/>feature auth<br/>[useAuth.ts]"]
  node_frontend_login_form["Login form<br/>auth UI<br/>[LoginForm.vue]"]
  node_frontend_shared_ui["Shared UI<br/>ui components"]
end

subgraph group_backend["Symfony API"]
  node_backend_v1["V1 API<br/>rest controllers"]
  node_backend_api_ctrl["API controllers<br/>http controllers"]
  node_backend_admin_ctrl["Admin area<br/>admin controllers"]
  node_backend_dto["Request DTOs<br/>validation dto"]
  node_backend_validation["Validation flow<br/>exception handling"]
  node_backend_rbac["RBAC layer<br/>authorization"]
  node_backend_permission_service["Permission service<br/>rbac service"]
  node_backend_models[("Domain model<br/>doctrine entities")]
  node_backend_repos["Repositories<br/>data access"]
  node_backend_migrations["Migrations<br/>schema history"]
  node_backend_fixtures["Fixtures<br/>seed data<br/>[AppFixtures.php]"]
  node_backend_mail["Reset email<br/>email template<br/>[email.html.twig]"]
end

subgraph group_external["External"]
  node_db[("Database<br/>relational store")]
  node_email["Mail system<br/>smtp/email"]
end

node_frontend_pages -->|"uses"| node_frontend_layouts
node_frontend_pages -->|"guarded by"| node_frontend_auth_mw
node_frontend_pages -->|"fetches via"| node_frontend_query
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_login_form -->|"drives"| node_frontend_auth
node_frontend_auth -->|"auth calls"| node_frontend_api
node_frontend_shared_ui -->|"supports"| node_frontend_pages
node_frontend_api -->|"HTTP"| node_backend_v1
node_backend_v1 -->|"binds"| node_backend_dto
node_backend_dto -->|"errors to"| node_backend_validation
node_backend_v1 -->|"checks"| node_backend_permission_service
node_backend_permission_service -->|"enforced by"| node_backend_rbac
node_backend_rbac -->|"uses"| node_backend_models
node_backend_api_ctrl -->|"queries"| node_backend_repos
node_backend_admin_ctrl -->|"authorizes"| node_backend_permission_service
node_backend_repos -->|"persists"| node_backend_models
node_backend_models -->|"stored in"| node_db
node_backend_migrations -->|"evolves"| node_db
node_backend_fixtures -->|"seeds"| node_db
node_backend_mail -->|"delivered via"| node_email
node_backend_v1 -->|"exposes"| node_backend_models

click node_frontend_pages "https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/app/pages"
click node_frontend_layouts "https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/app/layouts"
click node_frontend_auth_mw "https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/app/middleware/auth.ts"
click node_frontend_query "https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/app/plugins/vue-query.ts"
click node_frontend_api "https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/shared/composables/useApi.ts"
click node_frontend_auth "https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/features/auth/composables/useAuth.ts"
click node_frontend_login_form "https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/features/auth/components/LoginForm.vue"
click node_frontend_shared_ui "https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/layers/shared/components"
click node_backend_v1 "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Api/V1"
click node_backend_api_ctrl "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Api"
click node_backend_admin_ctrl "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Admin"
click node_backend_dto "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/DTO"
click node_backend_validation "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/EventListener"
click node_backend_rbac "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Security"
click node_backend_permission_service "https://github.com/mhannan-dev/symfony_acl/blob/main/api/src/Service/PermissionCheckService.php"
click node_backend_models "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Entity"
click node_backend_repos "https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Repository"
click node_backend_migrations "https://github.com/mhannan-dev/symfony_acl/tree/main/api/migrations"
click node_backend_fixtures "https://github.com/mhannan-dev/symfony_acl/blob/main/api/src/DataFixtures/AppFixtures.php"
click node_backend_mail "https://github.com/mhannan-dev/symfony_acl/blob/main/api/templates/reset_password/email.html.twig"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_pages,node_frontend_layouts,node_frontend_auth_mw,node_frontend_query,node_frontend_api,node_frontend_auth,node_frontend_login_form,node_frontend_shared_ui toneBlue
class node_backend_v1,node_backend_api_ctrl,node_backend_admin_ctrl,node_backend_dto,node_backend_validation,node_backend_rbac,node_backend_permission_service,node_backend_models,node_backend_repos,node_backend_migrations,node_backend_fixtures,node_backend_mail toneAmber
class node_db,node_email toneMint
```

## Components

### Nuxt UI

Standalone Nuxt 3/Vue 3 admin client that consumes the API over HTTP.

- [Route pages](https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/app/pages): nuxt pages · Feature-driven admin screens for users, groups, permissions, content types, activity logs, dashboard, and login. · `frontend/app/pages`
- [Layouts](https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/app/layouts): nuxt layouts · Separates authenticated admin screens from public/auth screens. · `frontend/app/layouts`
- [Auth middleware](https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/app/middleware/auth.ts): route guard · Client-side protection for authenticated routes. · `frontend/app/middleware/auth.ts`
- [Vue Query](https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/app/plugins/vue-query.ts): state plugin · Server-state management and request lifecycle handling for the UI. · `frontend/app/plugins/vue-query.ts`
- [API composable](https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/shared/composables/useApi.ts): http client · Shared client-side abstraction for calling the backend API. · `frontend/layers/shared/composables/useApi.ts`
- [Auth composable](https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/features/auth/composables/useAuth.ts): feature auth · Centralized frontend authentication behavior and session handling. · `frontend/layers/features/auth/composables/useAuth.ts`
- [Login form](https://github.com/mhannan-dev/symfony_acl/blob/main/frontend/layers/features/auth/components/LoginForm.vue): auth UI · Login entry point used by the public auth flow. · `frontend/layers/features/auth/components/LoginForm.vue`
- [Shared UI](https://github.com/mhannan-dev/symfony_acl/tree/main/frontend/layers/shared/components): ui components · 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](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Api/V1): rest controllers · Versioned public contract consumed by the Nuxt app. · `api/src/Controller/Api/V1`
- [API controllers](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Api): http controllers · Non-versioned JSON endpoints and shared API response handling. · `api/src/Controller/Api`
- [Admin area](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Controller/Admin): admin controllers · Backend-admin controller surface for internal/admin operations. · `api/src/Controller/Admin`
- [Request DTOs](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/DTO): validation dto · Typed request objects bridged from HTTP by a custom argument resolver. · `api/src/DTO`
- [Validation flow](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/EventListener): exception handling · Converts API validation failures into predictable JSON responses. · `api/src/EventListener`
- [RBAC layer](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Security): authorization · Permission evaluation and enforcement for users, groups, and permissions. · `api/src/Security`
- [Permission service](https://github.com/mhannan-dev/symfony_acl/blob/main/api/src/Service/PermissionCheckService.php): rbac service · Encapsulates permission checks used by controllers and security rules. · `api/src/Service/PermissionCheckService.php`
- [Domain model](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Entity): doctrine entities · Users, groups, permissions, content types, activity logs, and reset-password records. · `api/src/Entity`
- [Repositories](https://github.com/mhannan-dev/symfony_acl/tree/main/api/src/Repository): data access · Doctrine-backed query layer for each core entity. · `api/src/Repository`
- [Migrations](https://github.com/mhannan-dev/symfony_acl/tree/main/api/migrations): schema history · Database schema evolution for the Doctrine model. · `api/migrations`
- [Fixtures](https://github.com/mhannan-dev/symfony_acl/blob/main/api/src/DataFixtures/AppFixtures.php): seed data · Initial or sample data loaded into the database. · `api/src/DataFixtures/AppFixtures.php`
- [Reset email](https://github.com/mhannan-dev/symfony_acl/blob/main/api/templates/reset_password/email.html.twig): email template · Password-recovery email content rendered by Twig. · `api/templates/reset_password/email.html.twig`

### External

Infrastructure dependencies used by the application.

- **Database**: relational store · Primary persistence for doctrine entities, RBAC data, and audit history.
- **Mail system**: smtp/email · Outbound delivery channel for password reset messages.

## Connections

- 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.
