How f-lab-edu/temm-server works
1. Overall shape
- This is a Spring Boot / Java backend with a clear layered architecture: API → application services → domain model/repositories → infrastructure.
- The codebase is centered on two implemented business areas: social login / JWT authentication and product management. The README also describes broader store/location/inventory workflows, but those subsystems are not present in the current file tree.
2. Entry point and runtime
- TemmApplication is the application bootstrap.
- build.gradle.kts and Gradle wrapper indicate a standard JVM service build.
- application.yaml plus a separate test application.yaml provide environment-specific configuration.
- src/main/resources/static/login.html and index.html suggest a small server-rendered/static front door used for login/demo flows, not a full SPA frontend.
3. API layer
- HTTP endpoints live under app/api/controller.
- OauthController handles social login-related requests.
- ProductController exposes product CRUD/search endpoints.
- Request/response boundary objects live in app/api/dto, so controllers do not directly expose domain entities.
- SocialTypeConverter is a small API-adjacent adapter for translating incoming social provider values into domain types.
4. Application service layer
- Business orchestration happens in app/service.
- OAuthLoginService owns the login flow and token issuance.
- Product use cases are split by responsibility:
- ProductRegisterService
- ProductUpdateService
- ProductLifecycleService
- ProductQueryService
- SocialUserProviderFinder selects the correct social provider implementation based on login type.
- The service layer uses command/DTO-style inputs such as ProductRegisterCommand, ProductUpdateCommand, and LoginResult, keeping the API layer decoupled from persistence details.
5. Authentication and authorization flow
- The login flow is designed around social OAuth + JWT:
- the client starts with OAuth login,
- the backend exchanges/verifies social credentials,
- the backend resolves or creates a local user,
- JwtTokenProvider issues an application JWT.
- Security is enforced by custom filters in app/security:
- JwtAuthenticationFilter authenticates requests with JWTs,
- LoginCheckFilter enforces login requirements,
- LoginContextHolderFilter stores per-request authenticated user context,
- LoginContext carries the current authenticated identity.
- SecurityConfig wires these filters into the Spring Security chain.
6. External identity integration
- Social login is abstracted through domain interfaces in domain/provider:
- SocialTokenProvider
- SocialUserProvider
- Infrastructure implementations live in app/infrastructure:
- GoogleUserProvider
- RestSocialTokenProvider
- This makes the social identity provider a replaceable boundary; the application layer depends on interfaces, not Google-specific code.
7. Product domain model
- Core business entities live in domain/model:
- Product
- Sku
- Category
- CategoryProduct
- User
- SocialInfo
- Email
- ProductStatus
- SocialType
- The domain also contains validation and business exceptions such as SkuNotValidException and EmailNotValidException.
- The model suggests that product/category relationships and user identity are enforced at the domain level rather than only at the database layer.
8. Persistence boundaries
- Repository interfaces are in domain/repository:
- UserRepository
- ProductRepository
- CategoryRepository
- ProductQueryRepository
- Query-heavy reads are separated into ProductQueryRepository, with a concrete QueryDSL-backed implementation in app/infrastructure/ProductQueryDslRepository.
- QueryDslConfig indicates QueryDSL is used for more complex product search/filter queries beyond simple CRUD.
- JpaAuditingConfig implies entity timestamps and audit metadata are managed automatically.
9. Data flow for product use cases
- Product write operations typically flow:
- controller request DTO → service command → domain aggregate/entity logic → repository save/update.
- Product read/search operations flow:
- controller search request → ProductQueryService → query repository / QueryDSL → domain result DTOs → API response DTOs.
- Separate DTO sets exist for search, detail, status, and category views, which implies the API returns multiple projections rather than one generic product payload.
10. Error handling and response normalization
- The API layer has centralized exception handling in app/api/exception.
- GlobalExceptionHandler, GlobalErrorCode, and ErrorResponse standardize HTTP error output.
- Domain/business exceptions are distinct from API-level errors, which helps keep validation and business-rule failures consistent across controllers.
11. Infrastructure and integration config
- OauthConfig, WebClientConfig, and SecurityConfig are the main integration wiring points.
- WebClient is used for outbound HTTP calls to social providers.
- JwtTokenProvider is the application’s token infrastructure for stateless authentication.
- ProductQueryDslRepository is the main persistence-side infrastructure adapter beyond standard JPA repositories.
12. Database and schema management
- src/main/resources/db/migration/V1__users_categories_products_ddl.sql shows Flyway-style migration management.
- The schema currently covers users, categories, and products, matching the implemented feature set.
- The presence of TestContainerForMySQL indicates integration tests run against a real MySQL-compatible database environment rather than pure mocks.
13. Testing and quality gates
- Tests mirror the production package structure, covering controllers, services, infrastructure, security, and domain models.
- The repo includes a GitHub Actions workflow for SonarCloud analysis, indicating static quality checks are part of the delivery pipeline.
- This test layout reinforces the architectural boundaries: each layer has its own verification scope.
14. What is implemented vs. what is only in the README
- Implemented: OAuth login, JWT security, product CRUD/search, category-related domain pieces.
- Not visible in this repo tree: store management, location management, stock movement/adjustment workflows, alarms/notifications.
- So an architecture diagram for the current code should focus on the authentication and product subsystems, not the broader inventory operations described in the requirements.
15. Key diagram boundaries
- The most important boundaries to draw are:
- HTTP/API boundary at the controllers,
- security boundary at the custom JWT/login filters,
- application orchestration boundary at the service layer,
- domain boundary around entities and business rules,
- persistence boundary at repositories / QueryDSL / JPA,
- external identity boundary at Google/WebClient-based social login.
Main entry points: OAuthLoginService.java OAuth login · SecurityConfig.java App config · OauthController.java OAuth API · ProductController.java Product API
Components 18
Runtime
Application bootstrap and static entry resources.
- TemmApplication · Application bootstrap and component scan root.
src/main/java/io/github/ktg/temm/TemmApplication.java - Static front door · Minimal static/login pages used as a simple front entry.
src/main/resources/static/index.html
API
HTTP controllers, request/response DTOs, and API error handling.
- OAuth API · Handles social login requests and token handoff.
src/main/java/io/github/ktg/temm/app/api/controller/OauthController.java - Product API · Exposes product CRUD and search endpoints.
src/main/java/io/github/ktg/temm/app/api/controller/ProductController.java - API DTOs · Boundary objects for OAuth and product endpoints.
src/main/java/io/github/ktg/temm/app/api/dto/ProductSearchRequest.java - API errors · Normalizes controller failures into standard error responses.
src/main/java/io/github/ktg/temm/app/api/exception/GlobalExceptionHandler.java
Application
Use-case orchestration for authentication and products.
- OAuth login · Coordinates social login, user resolution, and JWT issuance.
src/main/java/io/github/ktg/temm/app/service/OAuthLoginService.java - Product use cases · Create, update, lifecycle, and query workflows for products.
src/main/java/io/github/ktg/temm/app/service/ProductRegisterService.java - Social finder · Chooses the correct social user provider by login type.
src/main/java/io/github/ktg/temm/app/service/SocialUserProviderFinder.java
Domain
Core business model, ports, and domain rules.
- Product model · Product, SKU, category linkage, and status rules.
src/main/java/io/github/ktg/temm/domain/model/Product.java - Identity model · User, social info, email, and social type concepts.
src/main/java/io/github/ktg/temm/domain/model/User.java - Domain ports · Persistence and social integration contracts used by the application layer.
src/main/java/io/github/ktg/temm/domain/provider/TokenProvider.java - Domain rules · Validation and business-rule failures for email, SKU, and related invariants.
src/main/java/io/github/ktg/temm/domain/exception/BusinessException.java
Infrastructure
Security, external identity, persistence adapters, and config.
- Security stack · JWT authentication, login checks, and per-request login context.
src/main/java/io/github/ktg/temm/app/security/JwtAuthenticationFilter.java - App config · Wires security, OAuth client access, QueryDSL, auditing, and WebClient.
src/main/java/io/github/ktg/temm/app/config/SecurityConfig.java - JWT provider · Issues and validates application JWTs for stateless auth.
src/main/java/io/github/ktg/temm/app/infrastructure/JwtTokenProvider.java - Social integration · Google provider access and outbound token exchange via WebClient.
src/main/java/io/github/ktg/temm/app/infrastructure/GoogleUserProvider.java
Persistence
Repository interfaces and query implementation boundary.
- Persistence layer · Repository interfaces and QueryDSL-backed product reads.
src/main/java/io/github/ktg/temm/domain/repository/ProductRepository.java
Connections 21
- TemmApplication → App config: boots with · Main application loads configuration and infrastructure beans.
- TemmApplication → Static front door: serves · Static pages provide a lightweight login/front door.
- OAuth API → API DTOs: uses · Maps HTTP payloads through request/response DTOs.
- Product API → API DTOs: uses · Maps product requests and responses through DTOs.
- OAuth API → OAuth login: calls · Delegates login orchestration to the application layer.
- Product API → Product use cases: calls · Delegates product workflows to application services.
- OAuth API → API errors: handled by · Controller failures are normalized into standard error responses.
- Product API → API errors: handled by · Controller failures are normalized into standard error responses.
- OAuth login → Social finder: selects · Resolves the provider implementation for a social login type.
- OAuth login → Social integration: verifies social login · Exchanges or validates external social credentials.
- OAuth login → JWT provider: issues token · Creates application JWTs after successful login.
- Product use cases → Product model: mutates · Applies product and category business rules.
- Product use cases → Persistence layer: persists via · Reads and writes through repository ports and query adapters.
- Security stack → JWT provider: uses · Security filters depend on token validation and creation logic.
- App config → Security stack: wires · Security configuration installs the custom filter chain.
- App config → Social integration: configures · OAuth and WebClient wiring support external identity calls.
- App config → Persistence layer: enables · JPA auditing and QueryDSL support persistence behavior.
- Product model → Domain rules: enforces · Business invariants raise domain-level exceptions.
- Identity model → Domain ports: depends on · Social and token abstractions stay at the domain boundary.
- Social integration → Domain ports: implements · Infrastructure provides concrete social provider adapters.
- Persistence layer → Domain ports: implements · Repository interfaces are backed by JPA and QueryDSL adapters.