# pratikvmarathe/rbac-api-templete architecture

> Architecture diagram of the GitHub repository pratikvmarathe/rbac-api-templete, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pratikvmarathe/rbac-api-templete
- Repository: https://github.com/pratikvmarathe/rbac-api-templete

## Overview

##### Project Type and Purpose
- This is a backend‐only, monolithic REST API built with Spring Boot (Java 17), designed as an RBAC (Role-Based Access Control) template.
- It exposes endpoints for user- and admin-level operations, secures them using JWT, and persists data in a relational database via Spring Data JPA.

##### High-Level Architectural Layers
- External Clients: any web/mobile client or API consumer.
- Edge/HTTP Layer: embedded Tomcat, CORS, and security filters.
- API Layer: Spring MVC controllers handling HTTP requests.
- Business Layer: service classes encapsulating domain logic.
- Data Layer: Spring Data repositories for CRUD on User and Token entities.
- Infrastructure: JWT utilities, validators, exception handlers.
- Persistence: relational database (e.g., PostgreSQL/MySQL).

##### Main Components
a. Clients
- Web/App/UI or third-party scripts invoking REST endpoints
b. API Gateway/Edge (Optional)
- CORS filter (CorsConfig)
- Security filter chain (JwtAuthenticationFilter, SecurityConfig)
c. Controllers
- UserController (user-level endpoints)
- AdminController (admin-level endpoints)
d. Services
- UserService
- UserTokenService
- CustomReactiveUserDetailsService (integrates with Spring Security)
e. Repositories
- UserRepository
- UserTokenModelRepository
- Projection interfaces (e.g., UserProfilePictureUrlProjection)
f. Utilities & Validators
- JwtUtil, SecretKeyUtil, PostalCodePatterns
- PhoneNumberValidator, PostalCodeValidator
- JwtReactiveAuthenticationManager
g. Database
- Tables for User, Role, UserTokenModel
h. Exception Handling
- TokenNotAvailableException

##### Relationships and Data Flows
- Flow through CORS & JWT filters → SecurityConfig establishes AuthenticationManager → JwtAuthenticationFilter validates tokens.
- After passing security, request → appropriate Controller.
- Controller delegates to Service layer (UserService / UserTokenService).
- Services call Repository interfaces → Database.
- Repositories return entities/projections → Services → Controllers → HTTP response → Clients.
- Exception flow: show TokenNotAvailableException thrown by Service/Filter and handled by a global exception handler (if any).

##### Architectural Patterns & Design Principles
- Layered (Onion/Clean) architecture: clearly separate presentation (controllers), business (services), and data (repositories).
- Use of Spring Security filter chain for authentication & authorization.
- Role-based access enforced in SecurityConfig and at controller method level.
- JWT stateless authentication—no server-side sessions.
- Validation via annotations & custom validators (e.g., @ValidPostalCode).

##### Detailed Component Breakdown (to include
- SopManagementSystemApplication (entry point)
- CorsConfig → applies CORS filters
- SecurityConfig → defines HTTP security rules, role mapping
- JwtAuthenticationFilter → intercepts requests, extracts & validates token
- JwtUtil & SecretKeyUtil → sign/verify JWT, manage secret keys
- Controllers (AdminController, UserController) → define REST endpoints
- Services → encapsulate business rules, token generation, user lookup
- CustomReactiveUserDetailsService & JwtReactiveAuthenticationManager → integrate with Spring Security for reactive flows
- Repositories → interface to database (CRUD, custom projections)
- Validators → enforce phone/postal code formats via annotations
- Exception classes → handle errors (e.g., missing token)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    SopApp["SopManagementSystemApplication"]:::entry

    %% External Clients
    Clients["Clients (Web/App/API)"]:::external

    %% Edge / HTTP Layer
    subgraph "Edge / HTTP Layer"
        CorsConfig["CorsConfig"]:::edge
        SecurityConfig["SecurityConfig"]:::security
        JwtAuthFilter["JwtAuthenticationFilter"]:::security
    end

    %% API Layer
    subgraph "API Layer"
        UserController["UserController"]:::controller
        AdminController["AdminController"]:::controller
    end

    %% Business Layer
    subgraph "Business Layer"
        UserService["UserService"]:::service
        UserTokenService["UserTokenService"]:::service
        CustomReactiveUserDetailsService["CustomReactiveUserDetailsService"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        UserRepository["UserRepository"]:::repository
        UserTokenModelRepository["UserTokenModelRepository"]:::repository
        UserProfilePictureUrlProjection["UserProfilePictureUrlProjection"]:::repository
    end

    %% Infrastructure & Validators
    subgraph "Infrastructure & Validators"
        JwtUtil["JwtUtil"]:::utility
        SecretKeyUtil["SecretKeyUtil"]:::utility
        PostalCodePatterns["PostalCodePatterns"]:::utility
        JwtReactiveAuthenticationManager["JwtReactiveAuthenticationManager"]:::utility
        PhoneNumberValidator["PhoneNumberValidator"]:::validator
        PostalCodeValidator["PostalCodeValidator"]:::validator
        ValidPhoneNumber["ValidPhoneNumber"]:::validator
        ValidPostalCode["ValidPostalCode"]:::validator
        TokenNotAvailableException["TokenNotAvailableException"]:::exception
    end

    %% Persistence
    DB[(Relational Database)]:::database

    %% Flows
    Clients -->|"HTTP Request"| SopApp
    SopApp -->|"Init Filters"| CorsConfig
    SopApp -->|"Init Security"| SecurityConfig
    Clients -->|"CORS Preflight"| CorsConfig
    CorsConfig -->|"Pass"| JwtAuthFilter
    SecurityConfig -->|"Configure"| JwtAuthFilter
    JwtAuthFilter -->|"Authenticated"| UserController
    JwtAuthFilter -->|"Authenticated"| AdminController

    UserController -->|"calls"| UserService
    AdminController -->|"calls"| UserService
    AdminController -->|"calls"| UserTokenService
    UserService -->|"uses"| UserRepository
    UserTokenService -->|"uses"| UserTokenModelRepository
    UserTokenModelRepository -->|"projection"| UserProfilePictureUrlProjection
    UserRepository -->|"CRUD"| DB
    UserTokenModelRepository -->|"CRUD"| DB

    %% Utility calls
    JwtAuthFilter -.->|"verify/sign"| JwtUtil
    JwtAuthFilter -.->|"load key"| SecretKeyUtil
    JwtReactiveAuthenticationManager -.->|"auth logic"| JwtUtil
    PhoneNumberValidator -.->|"validate"| UserService
    PostalCodeValidator -.->|"validate"| UserService
    PostalCodePatterns -.->|"patterns"| PostalCodeValidator
    ValidPhoneNumber -.->|"annotation"| PhoneNumberValidator
    ValidPostalCode -.->|"annotation"| PostalCodeValidator

    %% Exception flow
    UserService -->|"throws"| TokenNotAvailableException
    JwtAuthFilter -->|"throws"| TokenNotAvailableException

    %% Click Events
    click SopApp "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/SopManagementSystemApplication.java"
    click CorsConfig "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/configs/CorsConfig.java"
    click SecurityConfig "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/configs/SecurityConfig.java"
    click JwtAuthFilter "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/filters/JwtAuthenticationFilter.java"
    click UserController "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/controllers/UserController.java"
    click AdminController "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/controllers/AdminController.java"
    click UserService "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/services/UserService.java"
    click UserTokenService "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/services/UserTokenService.java"
    click CustomReactiveUserDetailsService "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/services/CustomReactiveUserDetailsService.java"
    click UserRepository "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/repositories/UserRepository.java"
    click UserTokenModelRepository "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/repositories/UserTokenModelRepository.java"
    click UserProfilePictureUrlProjection "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/repositories/projections/UserProfilePictureUrlProjection.java"
    click JwtUtil "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/utils/JwtUtil.java"
    click SecretKeyUtil "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/utils/SecretKeyUtil.java"
    click PostalCodePatterns "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/utils/PostalCodePatterns.java"
    click JwtReactiveAuthenticationManager "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/utils/JwtReactiveAuthenticationManager.java"
    click PhoneNumberValidator "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/validators/PhoneNumberValidator.java"
    click PostalCodeValidator "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/validators/PostalCodeValidator.java"
    click ValidPhoneNumber "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/validators/ValidPhoneNumber.java"
    click ValidPostalCode "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/validators/ValidPostalCode.java"
    click TokenNotAvailableException "https://github.com/pratikvmarathe/rbac-api-templete/blob/master/src/main/java/com/academy/exceptions/TokenNotAvailableException.java"

    %% Styles
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#efefef,stroke:#333,stroke-width:1px
    classDef edge fill:#ffdddd,stroke:#333,stroke-width:1px
    classDef security fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef controller fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef repository fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef utility fill:#dddddd,stroke:#333,stroke-width:1px
    classDef validator fill:#d4d4ff,stroke:#333,stroke-width:1px
    classDef exception fill:#ffdddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef database fill:#cccccc,stroke:#333,stroke-width:1px,shape:cylinder
```
