# travezvinueza/rolesandpermission architecture

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

- Interactive diagram: https://gitdiagram.com/travezvinueza/rolesandpermission
- Repository: https://github.com/travezvinueza/rolesandpermission

## Overview

##### Project type and purpose
- This is a Spring Boot–based RESTful API monolith focused on user/role/permission management, JWT‐based authentication/authorization, product CRUD, image upload, PayPal payments, PDF reporting, email notifications, and simple caching via Postgres UNLOGGED tables.

##### File structure
- Top‐level Maven project (pom.xml, mvnw).
- src/main/java/com/develop/backend:
- application – DTOs & mappers (API‐internal data contracts)
- domain – business entities, enums, service interfaces, repository interfaces
- domain/service/impl – business logic implementations
- infrastructure – configuration (JWT filter, security, PayPal, async executor, Swagger), REST controllers, exception handlers, utilities
- src/main/resources:
- Flyway migrations (db/migration)
- application.properties (database, SMTP, PayPal, JWT)
- JasperReports templates, email templates, file‐upload root
- src/test: unit/integration tests for controllers and application start

##### README for insights
- Confirms use of Spring Boot, Spring Security (JWT), Spring Data JPA (Postgres), Flyway, Spring Mail, PayPal SDK, Springdoc OpenAPI, JasperReports, Lombok.
- Describes major features: registration, login, token refresh, role & permission checks, product management, file upload, PDF reports, caching.

1. Client (Web/Mobile)
2. API Gateway / Spring Boot Application
– Security & Auth Filter (JWTAuthFilter)
– REST Controllers (AuthController, UserController, ProductController, etc.)
– Application Layer (DTOs, mappers)
– Domain Layer (Services & ServiceImpl)
– Data Layer (Spring Data JPA Repositories)
3. Relational Database (PostgreSQL + UNLOGGED cache tables + Flyway)
4. File Storage (local “uploads” directory)
5. External Services:
– SMTP Email Server
– PayPal API
6. Reporting Engine (JasperReports)
7. API Documentation (Springdoc OpenAPI UI)

- Client → HTTP request → JWTAuthFilter → Appropriate Controller
- Controller → Map request DTO → Service interface
- Service → Business logic, may call GenericCacheService for cached reads
- Service → Repository → SQL queries → PostgreSQL
- Service → FileUploadService → writes to local “uploads”
- AuthService → interacts with TokenRepository, UserRepository → issues JWT + refresh token
- EmailService → SMTP server → sends verification or notification emails
- PaypalService → PayPal REST API → processes payments
- ReportService (or domain service) → JasperReports → generates PDF
- Flyway (on app startup) → migrates schema & seed data in PostgreSQL

c. Architectural patterns & design principles:
- Layered (Controller → Service → Repository)
- DTO & Mapper pattern (separate internal entities from API contracts)
- Dependency Injection & inversion of control (Spring)
- Exception handling via @ControllerAdvice (GlobalExceptionHandler)
- Asynchronous configuration (AsyncExecutorConfig) for nonblocking tasks
- Security filter chain for stateless JWT auth
- Caching via custom GenericCacheService backed by Postgres UNLOGGED tables
- API documentation auto‐generation (Springdoc OpenAPI)

d. Key technologies/frameworks to annotate:
- Spring Boot, Spring Security, Spring Data JPA
- JWT (via JwtGenerator, JwtAuthFilter)
- Flyway (db/migration scripts)
- PostgreSQL (with UNLOGGED cache tables)
- Spring Mail
- PayPal SDK
- JasperReports
- Lombok
- Springdoc OpenAPI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client (Web/Mobile)"]:::client

    %% Application
    subgraph "Spring Boot Application" 
        direction TB
        EntryPoint["BackendApplication"]:::app
        JwtFilter["JwtAuthFilter"]:::security
        SecurityCfg["SecurityConfig"]:::security
        AsyncCfg["AsyncExecutorConfig"]:::config
        PayPalCfg["PayPalConfig"]:::config
        SwaggerCfg["Swagger (OpenAPI)"]:::config
        JwtUtil["JwtGenerator"]:::util

        subgraph "REST Controllers"
            direction TB
            AuthCtrl["AuthController"]:::controller
            UserCtrl["UserController"]:::controller
            ProductCtrl["ProductController"]:::controller
            CategoryCtrl["CategoryController"]:::controller
            OrderCtrl["OrderController"]:::controller
            OrderDetailCtrl["OrderDetailController"]:::controller
            PermissionCtrl["PermissionController"]:::controller
            RoleCtrl["RoleController"]:::controller
            PayPalCtrl["PayPalController"]:::controller
            CacheCtrl["GenericCacheController"]:::controller
            GlobalEx["GlobalExceptionHandler"]:::controller
        end

        subgraph "Application Layer"
            direction TB
            DTOs["DTOs"]:::app
            UserMapper["UserMapper/UserMapperImpl"]:::app
        end

        subgraph "Domain Layer"
            direction TB
            Entities["Entities"]:::domain
            Repos["Repositories"]:::domain
            Services["Service Interfaces"]:::domain
            ServiceImpl["Service Implementations"]:::domain
        end

        subgraph "Infrastructure Utilities"
            direction TB
            CacheUtils["CacheUtils"]:::util
        end
    end

    %% External & Persistence
    DB["PostgreSQL\n(with UNLOGGED cache tables)"]:::db
    Flyway["Flyway Migrations"]:::db
    FileStorage["File Storage (upload/)"]:::storage
    SMTP["SMTP Email Server"]:::external
    PayPalAPI["PayPal REST API"]:::external
    Jasper["JasperReports Engine"]:::external

    %% Flows
    Client -->|HTTP request| JwtFilter
    JwtFilter -->|validated| AuthCtrl
    AuthCtrl -->|uses| Services
    UserCtrl -->|uses| Services
    ProductCtrl -->|uses| Services
    CategoryCtrl -->|uses| Services
    OrderCtrl -->|uses| Services
    OrderDetailCtrl -->|uses| Services
    PermissionCtrl -->|uses| Services
    RoleCtrl -->|uses| Services
    PayPalCtrl -->|uses| Services
    CacheCtrl -->|uses| GenericCacheService

    Services -->|business logic| ServiceImpl
    ServiceImpl -->|CRUD queries| Repos
    Repos -->|SQL| DB
    Flyway -->|migrations| DB
    ServiceImpl -->|file upload| FileStorage
    ServiceImpl -->|email send| SMTP
    ServiceImpl -->|payment| PayPalAPI
    ServiceImpl -->|PDF generate| Jasper

    %% Click Events
    click EntryPoint "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/BackendApplication.java"
    click JwtFilter "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/config/JwtAuthFilter.java"
    click SecurityCfg "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/config/SecurityConfig.java"
    click AuthCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/AuthController.java"
    click UserCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/UserController.java"
    click ProductCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/ProductController.java"
    click CategoryCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/CategoryController.java"
    click OrderCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/OrderController.java"
    click OrderDetailCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/OrderDetailController.java"
    click PermissionCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/PermissionController.java"
    click RoleCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/RoleController.java"
    click PayPalCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/PayPalController.java"
    click CacheCtrl "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/controller/GenericCacheController.java"
    click DTOs "https://github.com/travezvinueza/rolesandpermission/tree/main/src/main/java/com/develop/backend/application/dto"
    click UserMapper "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/application/mapper/UserMapper.java"
    click Entities "https://github.com/travezvinueza/rolesandpermission/tree/main/src/main/java/com/develop/backend/domain/entity"
    click Repos "https://github.com/travezvinueza/rolesandpermission/tree/main/src/main/java/com/develop/backend/domain/repository"
    click Services "https://github.com/travezvinueza/rolesandpermission/tree/main/src/main/java/com/develop/backend/domain/service"
    click ServiceImpl "https://github.com/travezvinueza/rolesandpermission/tree/main/src/main/java/com/develop/backend/domain/service/impl"
    click AsyncCfg "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/config/AsyncExecutorConfig.java"
    click PayPalCfg "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/config/PayPalConfig.java"
    click SwaggerCfg "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/config/Swagger.java"
    click JwtUtil "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/util/JwtGenerator.java"
    click CacheUtils "https://github.com/travezvinueza/rolesandpermission/blob/main/src/main/java/com/develop/backend/insfraestructure/util/CacheUtils.java"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef app fill:#bbf,stroke:#333,stroke-width:1px
    classDef security fill:#fbb,stroke:#333,stroke-width:1px
    classDef config fill:#dfd,stroke:#333,stroke-width:1px
    classDef controller fill:#bfb,stroke:#333,stroke-width:1px
    classDef domain fill:#ffd,stroke:#333,stroke-width:1px
    classDef util fill:#ddf,stroke:#333,stroke-width:1px
    classDef db fill:#fea,stroke:#333,stroke-width:1px
    classDef storage fill:#ffa,stroke:#333,stroke-width:1px
    classDef external fill:#aff,stroke:#333,stroke-width:1px
```
