# devondragon/springuserframework architecture

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

- Interactive diagram: https://gitdiagram.com/devondragon/springuserframework
- Repository: https://github.com/devondragon/springuserframework

## Overview

##### Project Type and Purpose
- Project Type: A Spring Boot auto-configuration library (ds-spring-user-framework).
- Purpose: Provide plug-and-play user registration, authentication, authorization, profile management, audit logging, password reset, and SSO/OAuth2 support for any Spring Boot application.

##### File Structure for Architectural Boundaries
- src/main/java/com/digitalsanctuary/spring/user
- auto-configuration & registrar (UserAutoConfigurationRegistrar.java, UserConfiguration.java)
- API layer (UserAPI)
- Web controllers (UserActionController, UserPageController)
- Service layer (UserService, AuthorityService, LoginHelperService, etc.)
- Persistence layer (JPA entities under persistence/model + Spring Data repositories)
- Event framework (AuditEvent, OnRegistrationCompleteEvent, UserPreDeleteEvent + listeners)
- Mail (MailService, MailContentBuilder + email templates)
- Security (WebSecurityConfig, CustomOAuth2AuthenticationEntryPoint)
- Scheduling (ExpiredTokenCleanJob, FileAuditLogFlushScheduler)
- src/main/resources
- configuration metadata, default properties, message bundles, Thymeleaf mail templates
- External integrations
- Database (MariaDB or any JDBC-backed)
- SMTP mail server
- OAuth2/OpenID Connect providers (Google, Facebook, Keycloak, etc.)

##### Main Components
1. Host Application (a Spring Boot app that pulls in the framework via Maven/Gradle)
2. AutoConfiguration Module
– UserAutoConfigurationRegistrar
– UserConfiguration
3. API & Web Layer
– REST endpoints (UserAPI)
– MVC controllers (UserPageController, UserActionController)
4. Service Layer
– UserService (core business logic)
– AuthorityService, LoginAttemptService, OAuth2UserService, UserVerificationService, etc.
5. Persistence Layer
– JPA Entities (User, Role, Privilege, VerificationToken, PasswordResetToken, BaseUserProfile)
– Spring Data Repositories
– Schema (db-scripts/mariadb-schema.sql)
6. Event & Audit Subsystem
– AuditEvent, AuditEventListener → FileAuditLogWriter or custom AuditLogWriter
– OnRegistrationCompleteEvent → MailService → SMTP Server
– UserPreDeleteEvent → application’s cleanup listener
7. Security Configuration
– WebSecurityConfig (filters, CSRF protection, login/logout handlers)
– OAuth2 clients (Google, Facebook, Keycloak)
8. External Systems
– SMTP server
– OAuth2 provider(s)
– Database

##### Relationships & Data Flows
- At startup: Spring Boot scans AutoConfigurationRegistrar → registers beans from UserConfiguration.
- User request → Controller/API → Service → Repository → Database
- Registration: Service publishes OnRegistrationCompleteEvent → EventListener triggers MailService → SMTP
- Login: Service checks credentials → on success/failure triggers AuditEvent → AuditEventListener writes to log
- Scheduled Jobs: ExpiredTokenCleanJob removes old tokens; FileAuditLogFlushScheduler periodically flushes log buffers.
- OAuth2 login: WebSecurityConfig delegates to DSOAuth2UserService/DSOidcUserService → fetch user info from external provider → maps to DSUserDetails → Service creates/updates user.

##### Architectural Patterns & Design Principles
- Layered Architecture: Controller → Service → Repository
- Spring Auto-Configuration: decoupled, convention-over-configuration
- Event-Driven Hooks: extensibility via Spring ApplicationEvents (audit, pre-delete)
- Pluggable Modules: mail, security, profile extension via BaseUserProfile
- Scheduling for background jobs (token cleanup, audit log flush)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Host Application"
        subgraph "Auto-Configuration"
            UACR["UserAutoConfigurationRegistrar"]:::framework
            UC["UserConfiguration"]:::framework
        end
        subgraph "API & Web"
            API["UserAPI"]:::framework
            UACtrl["UserActionController"]:::framework
            UPctrl["UserPageController"]:::framework
        end
        subgraph "Services"
            US["UserService"]:::framework
            AuthS["AuthorityService"]:::framework
            LAS["LoginAttemptService"]:::framework
            LHS["LoginHelperService"]:::framework
            LSS["LoginSuccessService"]:::framework
            LoSS["LogoutSuccessService"]:::framework
            DS2["DSOAuth2UserService"]:::framework
            DS3["DSOidcUserService"]:::framework
            UVS["UserVerificationService"]:::framework
            UES["UserEmailService"]:::framework
        end
        subgraph "Persistence"
            subgraph Entities
                U["User"]:::framework
                R["Role"]:::framework
                P["Privilege"]:::framework
                VT["VerificationToken"]:::framework
                PRT["PasswordResetToken"]:::framework
            end
            subgraph Repositories
                UR["UserRepository"]:::framework
                RR["RoleRepository"]:::framework
                PR["PrivilegeRepository"]:::framework
                VTR["VerificationTokenRepository"]:::framework
                PRTR["PasswordResetTokenRepository"]:::framework
            end
            DB[(Database)]:::db
        end
        subgraph "Events & Audit"
            AE["AuditEvent"]:::framework
            ORCE["OnRegistrationCompleteEvent"]:::framework
            UPDE["UserPreDeleteEvent"]:::framework
            AEL["AuditEventListener"]:::framework
            RL["RegistrationListener"]:::framework
            FALW["FileAuditLogWriter"]:::framework
            FALS["FileAuditLogFlushScheduler"]:::framework
        end
        subgraph "Mail Subsystem"
            MS["MailService"]:::framework
            MCB["MailContentBuilder"]:::framework
        end
        subgraph "Security"
            WSC["WebSecurityConfig"]:::framework
            COAE["CustomOAuth2AuthenticationEntryPoint"]:::framework
        end
        subgraph "Scheduling Jobs"
            ETCJ["ExpiredTokenCleanJob"]:::framework
        end
    end

    SMTP["SMTP Mail Server"]:::external
    OAUTH["OAuth2 Providers"]:::external

    %% Relationships
    UACR --> UC
    UC --> API
    UC --> UACtrl
    UC --> UPctrl
    API --> US
    UACtrl --> US
    UPctrl --> US

    US --> UR
    AuthS --> UR
    LAS --> UR
    LHS --> UR
    LSS --> UR
    LoSS --> UR
    UVS --> UR
    UES --> UR

    UR --> DB
    RR --> DB
    PR --> DB
    VTR --> DB
    PRTR --> DB

    US -.-> AE
    AE --> AEL
    AEL --> FALW
    FALW --> DB

    ORCE -.-> RL
    RL --> MS
    MS --> SMTP

    ETCJ --> VTR
    FALS --> FALW

    OAUTH --> WSC
    WSC --> DS2
    WSC --> DS3
    DS2 --> US
    DS3 --> US

    %% Click Events
    click UACR "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/UserAutoConfigurationRegistrar.java"
    click UC "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/UserConfiguration.java"
    click API "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/api/UserAPI.java"
    click UACtrl "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/controller/UserActionController.java"
    click UPctrl "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/controller/UserPageController.java"
    click US "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/UserService.java"
    click AuthS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/AuthorityService.java"
    click LAS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/LoginAttemptService.java"
    click LHS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/LoginHelperService.java"
    click LSS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/LoginSuccessService.java"
    click LoSS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/LogoutSuccessService.java"
    click DS2 "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/DSOAuth2UserService.java"
    click DS3 "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/DSOidcUserService.java"
    click UVS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/UserVerificationService.java"
    click UES "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/service/UserEmailService.java"
    click U "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/model/User.java"
    click R "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/model/Role.java"
    click P "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/model/Privilege.java"
    click VT "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/model/VerificationToken.java"
    click PRT "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/model/PasswordResetToken.java"
    click UR "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/repository/UserRepository.java"
    click RR "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/repository/RoleRepository.java"
    click PR "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/repository/PrivilegeRepository.java"
    click VTR "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/repository/VerificationTokenRepository.java"
    click PRTR "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/persistence/repository/PasswordResetTokenRepository.java"
    click AE "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/audit/AuditEvent.java"
    click ORCE "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/event/OnRegistrationCompleteEvent.java"
    click UPDE "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/event/UserPreDeleteEvent.java"
    click AEL "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/audit/AuditEventListener.java"
    click RL "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/listener/RegistrationListener.java"
    click FALW "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/audit/FileAuditLogWriter.java"
    click FALS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/audit/FileAuditLogFlushScheduler.java"
    click MS "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/mail/MailService.java"
    click MCB "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/mail/MailContentBuilder.java"
    click WSC "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/security/WebSecurityConfig.java"
    click COAE "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/security/CustomOAuth2AuthenticationEntryPoint.java"
    click ETCJ "https://github.com/devondragon/springuserframework/blob/main/src/main/java/com/digitalsanctuary/spring/user/jobs/ExpiredTokenCleanJob.java"

    %% Styles
    classDef framework fill:#e5f5e0,stroke:#2e7d32,stroke-width:1px
    classDef db fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef external fill:#ffe082,stroke:#f9a825,stroke-width:1px
```
