# spacecodee/springboot-security-open-template architecture

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

- Interactive diagram: https://gitdiagram.com/spacecodee/springboot-security-open-template
- Repository: https://github.com/spacecodee/springboot-security-open-template

## Overview

##### Main Components
- API/Presentation Layer – Represent all controllers (e.g., auth, user [developer, editor, guest, etc.], core endpoints) that expose REST endpoints. Note that controllers often delegate to services.
- Business/Service Layer – Capture the key service modules. There are two main groups: core services (module, operation, permission, role, etc.) and security-specific services (JWT token generation/validation, authentication service, token lifecycle & cleanup, rate limiting, etc.).
- Data Access/Persistence Layer – Identify JPA repositories and associated entity classes (e.g., UserEntity, JwtTokenEntity, and other domain entities such as ModuleEntity, RoleEntity, etc.) that communicate with the PostgreSQL database.
- Security Infrastructure – Highlight the security configuration components including filters (JWTAuthenticationFilter, LocaleResolverFilter, RateLimitFilter), security configuration classes (HttpSecurityConfig, MethodSecurityConfig, CorsConfig, PasswordEncoderConfig), custom authorization managers/evaluators, and token validators.
- Exception and Utilities – Although not a primary flow, note the exception handlers (GlobalExceptionHandler) and utility components that support validations, message resolutions (for i18n), and caching (using Guava).
- External Artifacts/Integrations – Indicate external resources like the PostgreSQL database, Swagger/OpenAPI documentation endpoints (Swagger UI and API docs), and the .devcontainer containerization setup for development.

##### Relationships and Data Flow
- From the Service Layer, there are calls to the Persistence Layer (Repository → Database) to retrieve or update data.
- The security filters (JWTAuthenticationFilter, RateLimitFilter) intercept incoming requests before they reach the controllers, enforcing JWT-based authentication and setting thread-locals for locale/context.
- The authentication and token lifecycle modules in the Security Service interact with the token repositories for token validation, cleanup, and state transitions.
- How exception handling (GlobalExceptionHandler) integrates and responds to errors thrown in any layer.

##### Important Architectural Patterns and Principles
- Layered Architecture: Separate presentation, service, and persistence to support testability and maintainability.
- Security Best Practices: Implement JWT-based authentication, token invalidation (on user updates), RBAC and permission caching, and dynamic path matching.
- Modular Design: The clear separation of concerns (into distinct packages like controller, service, persistence, configuration, exception, security) indicates modularization and a clean separation of responsibilities.
- Internationalization: Inclusion of locale-based response handling.

- Service components to a persistence layer that includes repositories and the database.
- Labels to each element (e.g., “JwtAuthenticationFilter”, “RoleServiceImpl”, “IUserRepository”, “CustomAuthorizationManager”) to reflect the actual classes/modules from the project structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client"]:::external

    subgraph "Security Infrastructure"
        SF["Security Filters\n(JwtAuthenticationFilter, RateLimitFilter,\nLocaleResolverFilter)"]:::security
        SC["Security Configurations\n(HttpSecurityConfig, MethodSecurityConfig,\nCorsConfig, PasswordEncoderConfig)"]:::security
    end

    Client -->|"Request"| SF

    subgraph "API/Presentation Layer"
        APICtrl["Controllers\n(Auth, User, Core endpoints)"]:::api
    end

    SF -->|"Forward"| APICtrl

    subgraph "Business/Service Layer"
        CoreSRV["Core Services\n(Module, Operation, Permission, Role)"]:::service
        SecSRV["Security Services\n(Authentication, Token Management,\nRate Limiting, Token Cleanup)"]:::service
    end

    APICtrl -->|"DelegatesTo"| CoreSRV
    APICtrl -->|"DelegatesTo"| SecSRV

    subgraph "Data Access/Persistence Layer"
        Repos["Repositories\n(JPA Repositories)"]:::persistence
        Entities["Entities\n(UserEntity, JwtTokenEntity, etc.)"]:::persistence
        DB[("PostgreSQL DB")]:::database
    end

    CoreSRV -->|"Calls"| Repos
    SecSRV -->|"Calls"| Repos
    Repos -->|"Queries"| DB

    subgraph "Exception & Utilities"
        Exception["GlobalExceptionHandler"]:::exception
        LocaleUtil["Locale Utilities"]:::exception
        MessageUtil["Message & General Utilities"]:::exception
    end

    APICtrl -->|"HandlesError"| Exception

    subgraph "External Integrations"
        SwaggerUI["Swagger UI"]:::integration
        DevContainer["Dev Container Setup"]:::integration
    end

    APICtrl -->|"DocsAvailable"| SwaggerUI

    %% Click Events
    click APICtrl "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/controller"
    click CoreSRV "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/service/core"
    click SecSRV "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/service/security"
    click Repos "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/persistence/repository"
    click Entities "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/persistence/entity"
    click SF "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/security"
    click SC "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/security/config"
    click Exception "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/exceptions/handler"
    click LocaleUtil "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/language"
    click MessageUtil "https://github.com/spacecodee/springboot-security-open-template/tree/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/utils"
    click SwaggerUI "https://github.com/spacecodee/springboot-security-open-template/blob/main/src/main/java/com/spacecodee/springbootsecurityopentemplate/config/SwaggerConfig.java"
    click DevContainer "https://github.com/spacecodee/springboot-security-open-template/blob/main/.devcontainer"

    %% Styles
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef service fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef persistence fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef security fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef exception fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
    classDef integration fill:#fefefe,stroke:#6c757d,stroke-width:2px;
    classDef database fill:#e2eefd,stroke:#31708f,stroke-width:2px;
```
