# ebron-sasack/buynow-user-service architecture

> Architecture diagram of the GitHub repository ebron-sasack/buynow-user-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ebron-sasack/buynow-user-service
- Repository: https://github.com/ebron-sasack/buynow-user-service

## Overview

#### Purpose and Runtime
BuyNow User Service is a Java 21 Spring Boot microservice for customer profiles and multiple user addresses. Its executable entry point is `src/main/java/com/buynow/user_service/UserServiceApplication.java`; runtime settings, including relational-database connectivity, belong in `src/main/resources/application.properties`. Maven build/dependency management is defined by `pom.xml`.

#### HTTP/API Boundary
Spring MVC controllers expose the user and address REST boundary:
- `src/main/java/com/buynow/user_service/controller/UserController.java`
- `src/main/java/com/buynow/user_service/controller/AddressController.java`

The documented flow covers retrieval and updates for `/api/v1/users/{id}`, plus creation and listing of `/api/v1/users/{id}/addresses`. `src/main/java/com/buynow/user_service/configuration/WebConfig.java` is the web-layer configuration boundary.

#### Request and Response Contracts
Controllers accept purpose-specific mutation DTOs rather than persistence entities:
- `src/main/java/com/buynow/user_service/dto/request/CreateUserRequest.java`
- `src/main/java/com/buynow/user_service/dto/request/UpdateUserRequest.java`
- `src/main/java/com/buynow/user_service/dto/request/CreateAddressRequest.java`

Responses are projected through `src/main/java/com/buynow/user_service/dto/response/UserResponse.java` and `src/main/java/com/buynow/user_service/dto/response/AddressResponse.java`, separating public API representation from JPA storage models.

#### Domain Model
The core persistent aggregate is user profile data in `src/main/java/com/buynow/user_service/entity/User.java`, with associated addresses in `src/main/java/com/buynow/user_service/entity/Address.java`. Address classification is represented by `src/main/java/com/buynow/user_service/enums/AddressType.java`. The tree also contains `src/main/java/com/buynow/user_service/entity/SellerApplication.java` and its lifecycle enum `src/main/java/com/buynow/user_service/enums/ApplicationStatus.java`, indicating a seller-application domain model, though no corresponding controller/service/repository is present.

#### Application-Service Layer
Business orchestration is defined through service interfaces and implementations:
- `src/main/java/com/buynow/user_service/service/UserService.java`
- `src/main/java/com/buynow/user_service/service/implementation/UserServiceImpl.java`
- `src/main/java/com/buynow/user_service/service/implementation/AddressServiceImpl.java`

Primary control flow is controller → service → repository → relational database. Services own user existence checks, profile/address updates, relationship handling, and conversion between request/entity/response shapes.

#### Persistence Boundary
Spring Data JPA repositories isolate database access:
- `src/main/java/com/buynow/user_service/repository/UserRepository.java`
- `src/main/java/com/buynow/user_service/repository/AddressRepository.java`

The service is designed for MySQL or PostgreSQL, selected/configured externally through application properties. Entity classes are the JPA mapping boundary; clients do not directly receive them.

#### Error and API Envelope Handling
Domain and validation failures are represented by typed exceptions such as `src/main/java/com/buynow/user_service/exception/ResourceNotFoundException.java` and `src/main/java/com/buynow/user_service/exception/AlreadyExistsException.java`. `src/main/java/com/buynow/user_service/exception/GlobalExceptionHandler.java` centralizes their HTTP translation. Shared success/error payload types reside in `src/main/java/com/buynow/user_service/payload/ApiResponse.java` and `src/main/java/com/buynow/user_service/payload/ErrorResponse.java`.

Main entry points: [`src/main/java/com/buynow/user_service/controller/UserController.java`](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/controller/UserController.java) (User REST controller), [`src/main/java/com/buynow/user_service/controller/AddressController.java`](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/controller/AddressController.java) (Address REST controller), [`src/main/java/com/buynow/user_service/service/implementation/UserServiceImpl.java`](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/implementation/UserServiceImpl.java) (User service), [`src/main/java/com/buynow/user_service/service/implementation/AddressServiceImpl.java`](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/implementation/AddressServiceImpl.java) (Address service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app{{"Spring Boot application<br/>entry point"}}
  node_build["Maven build<br/>[pom.xml]"]
  node_settings["Runtime settings<br/>properties"]
end

subgraph group_api["HTTP API"]
  node_web_config["Web configuration<br/>Spring MVC config<br/>[WebConfig.java]"]
  node_user_controller["User REST controller"]
  node_address_controller["Address REST controller"]
  node_error_handler["Global exception handler<br/>HTTP error translation"]
  node_api_envelopes["API response envelopes<br/>payload contracts<br/>[ApiResponse.java]"]
end

subgraph group_application["Application Services"]
  node_user_service["User service contract<br/>service interface<br/>[UserService.java]"]
  node_user_service_impl["User service<br/>service implementation"]
  node_address_service["Address service<br/>service implementation"]
end

subgraph group_domain["Domain &amp; Contracts"]
  node_request_dtos["Mutation request DTOs<br/>API contracts"]
  node_response_dtos["Response DTOs<br/>API contracts<br/>[UserResponse.java]"]
  node_user_entity["User profile<br/>JPA entity<br/>[User.java]"]
  node_address_entity["Address<br/>JPA entity<br/>[Address.java]"]
  node_seller_application["Seller application<br/>JPA entity"]
end

subgraph group_persistence["Persistence"]
  node_user_repository["User repository<br/>Spring Data JPA"]
  node_address_repository["Address repository<br/>Spring Data JPA"]
  node_database[("MySQL or PostgreSQL<br/>relational database")]
end

node_build -->|"builds"| node_app
node_settings -->|"configures"| node_app
node_app -->|"starts MVC"| node_web_config
node_web_config -->|"configures"| node_user_controller
node_web_config -->|"configures"| node_address_controller
node_user_controller -->|"accepts"| node_request_dtos
node_address_controller -->|"accepts"| node_request_dtos
node_user_controller -->|"delegates to"| node_user_service
node_user_service -->|"implemented by"| node_user_service_impl
node_address_controller -->|"delegates to"| node_address_service
node_user_service_impl -->|"loads and saves"| node_user_repository
node_user_service_impl -->|"updates addresses"| node_address_repository
node_address_service -->|"checks user"| node_user_repository
node_address_service -->|"loads and saves"| node_address_repository
node_user_repository -->|"maps"| node_user_entity
node_address_repository -->|"maps"| node_address_entity
node_user_entity -->|"has addresses"| node_address_entity
node_user_repository -->|"persists to"| node_database
node_address_repository -->|"persists to"| node_database
node_user_service_impl -->|"projects to"| node_response_dtos
node_address_service -->|"projects to"| node_response_dtos
node_user_controller -->|"returns"| node_response_dtos
node_address_controller -->|"returns"| node_response_dtos
node_error_handler -->|"produces errors"| node_api_envelopes
node_user_controller -.->|"failures handled by"| node_error_handler
node_address_controller -.->|"failures handled by"| node_error_handler

click node_app "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/UserServiceApplication.java"
click node_build "https://github.com/ebron-sasack/buynow-user-service/blob/main/pom.xml"
click node_settings "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/resources/application.properties"
click node_web_config "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/configuration/WebConfig.java"
click node_user_controller "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/controller/UserController.java"
click node_address_controller "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/controller/AddressController.java"
click node_request_dtos "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/dto/request/CreateUserRequest.java"
click node_response_dtos "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/dto/response/UserResponse.java"
click node_user_service "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/UserService.java"
click node_user_service_impl "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/implementation/UserServiceImpl.java"
click node_address_service "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/implementation/AddressServiceImpl.java"
click node_user_entity "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/entity/User.java"
click node_address_entity "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/entity/Address.java"
click node_seller_application "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/entity/SellerApplication.java"
click node_user_repository "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/repository/UserRepository.java"
click node_address_repository "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/repository/AddressRepository.java"
click node_error_handler "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/exception/GlobalExceptionHandler.java"
click node_api_envelopes "https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/payload/ApiResponse.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_build,node_settings toneBlue
class node_web_config,node_user_controller,node_address_controller,node_error_handler,node_api_envelopes toneAmber
class node_user_service,node_user_service_impl,node_address_service toneMint
class node_request_dtos,node_response_dtos,node_user_entity,node_address_entity,node_seller_application toneRose
class node_user_repository,node_address_repository,node_database toneIndigo
```

## Components

### Runtime

- [Spring Boot application](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/UserServiceApplication.java): entry point · `src/main/java/com/buynow/user_service/UserServiceApplication.java`
- [Maven build](https://github.com/ebron-sasack/buynow-user-service/blob/main/pom.xml): build · `pom.xml`
- [Runtime settings](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/resources/application.properties): properties · Configures relational database connectivity. · `src/main/resources/application.properties`

### HTTP API

- [Web configuration](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/configuration/WebConfig.java): Spring MVC config · `src/main/java/com/buynow/user_service/configuration/WebConfig.java`
- [User REST controller](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/controller/UserController.java): controller · Handles profile retrieval and updates. · `src/main/java/com/buynow/user_service/controller/UserController.java`
- [Address REST controller](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/controller/AddressController.java): controller · Handles user address creation and listing. · `src/main/java/com/buynow/user_service/controller/AddressController.java`
- [Global exception handler](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/exception/GlobalExceptionHandler.java): HTTP error translation · Maps typed domain failures to API errors. · `src/main/java/com/buynow/user_service/exception/GlobalExceptionHandler.java`
- [API response envelopes](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/payload/ApiResponse.java): payload contracts · Shared success and error payloads. · `src/main/java/com/buynow/user_service/payload/ApiResponse.java`

### Application Services

- [User service contract](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/UserService.java): service interface · `src/main/java/com/buynow/user_service/service/UserService.java`
- [User service](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/implementation/UserServiceImpl.java): service implementation · Orchestrates profile operations and mappings. · `src/main/java/com/buynow/user_service/service/implementation/UserServiceImpl.java`
- [Address service](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/service/implementation/AddressServiceImpl.java): service implementation · Owns address relationship handling and mappings. · `src/main/java/com/buynow/user_service/service/implementation/AddressServiceImpl.java`

### Domain & Contracts

- [Mutation request DTOs](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/dto/request/CreateUserRequest.java): API contracts · Create/update user and create address inputs. · `src/main/java/com/buynow/user_service/dto/request/CreateUserRequest.java`
- [Response DTOs](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/dto/response/UserResponse.java): API contracts · Public user and address projections. · `src/main/java/com/buynow/user_service/dto/response/UserResponse.java`
- [User profile](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/entity/User.java): JPA entity · `src/main/java/com/buynow/user_service/entity/User.java`
- [Address](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/entity/Address.java): JPA entity · Classified by address type. · `src/main/java/com/buynow/user_service/entity/Address.java`
- [Seller application](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/entity/SellerApplication.java): JPA entity · Present domain model without an exposed application flow. · `src/main/java/com/buynow/user_service/entity/SellerApplication.java`

### Persistence

- [User repository](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/repository/UserRepository.java): Spring Data JPA · `src/main/java/com/buynow/user_service/repository/UserRepository.java`
- [Address repository](https://github.com/ebron-sasack/buynow-user-service/blob/main/src/main/java/com/buynow/user_service/repository/AddressRepository.java): Spring Data JPA · `src/main/java/com/buynow/user_service/repository/AddressRepository.java`
- **MySQL or PostgreSQL**: relational database · Selected through runtime properties.

## Connections

- Maven build → Spring Boot application: builds
- Runtime settings → Spring Boot application: configures
- Spring Boot application → Web configuration: starts MVC
- Web configuration → User REST controller: configures
- Web configuration → Address REST controller: configures
- User REST controller → Mutation request DTOs: accepts
- Address REST controller → Mutation request DTOs: accepts
- User REST controller → User service contract: delegates to
- User service contract → User service: implemented by
- Address REST controller → Address service: delegates to
- User service → User repository: loads and saves
- User service → Address repository: updates addresses
- Address service → User repository: checks user
- Address service → Address repository: loads and saves
- User repository → User profile: maps
- Address repository → Address: maps
- User profile → Address: has addresses
- User repository → MySQL or PostgreSQL: persists to
- Address repository → MySQL or PostgreSQL: persists to
- User service → Response DTOs: projects to
- Address service → Response DTOs: projects to
- User REST controller → Response DTOs: returns
- Address REST controller → Response DTOs: returns
- Global exception handler → API response envelopes: produces errors
- User REST controller → Global exception handler: failures handled by
- Address REST controller → Global exception handler: failures handled by