How devondragon/springuserframework works
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)