# valdetad/stockmanagement architecture

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

- Interactive diagram: https://gitdiagram.com/valdetad/stockmanagement
- Repository: https://github.com/valdetad/stockmanagement

## Overview

##### Project type and purpose
- This is a Java-based backend application built with Spring Boot and Maven that exposes a set of RESTful APIs for managing products, markets, stocks, purchases, and users. It does not include a separate frontend; clients consume its endpoints via HTTP (e.g., Postman or a web/mobile frontend).

##### File structure
- Top level:
- pom.xml, mvnw wrappers – build and dependency management
- src/main/java/com/example/StockManagement – application code
- src/main/resources/application.properties – externalized configuration
- src/test – unit/integration tests
- data folder – an embedded H2 test database
- Under src/main/java:
- controller – REST controllers (API layer)
- services – business logic layer
- repository – Spring Data JPA layer (data access)
- data/model – JPA entities
- data/dto – input/output data transfer objects
- data/constants – enums for roles, statuses, categories
- security – JWT-based authentication and authorization
- Notice the classic layered architecture (Controller → Service → Repository → Database) and JWT security filters intercepting requests.

##### README insights
- Confirms REST APIs for Product, Stock, Purchase, Market, and User Authentication.
- Uses MySQL for persistence and JWT Bearer tokens for security.
- Export functionality to Excel and PDF via ImportExportService.

a. Main components
- Clients (Web app, Postman, Mobile)
- API Layer (Spring MVC Controllers)
- Security Layer (JWT filter, AuthenticationService)
- Service Layer (ProductService, StockService, PurchaseService, MarketService, ImportExportService)
- Persistence Layer (Spring Data JPA Repositories)
- Database (MySQL)
- External Libraries (PDF/Excel generation)
b. Relationships and interactions
1. Client sends HTTP requests with/without JWT
2. JWTAuthenticationFilter validates token → AuthenticationService
3. Valid requests go to Controller methods
4. Controllers invoke Service layer methods
5. Services apply business rules and call Repositories
6. Repositories perform CRUD operations on MySQL
7. ImportExportService accesses data via Services/Repos and uses libraries to generate Excel/PDF, returning binary streams
c. Architectural patterns
- Layered (Controller → Service → Repository → Database)
- DTO pattern to decouple API contracts from entities
- JWT filter chain in SecurityConfig for stateless authentication
d. Technologies/frameworks
- Spring Boot (web, data-jpa, security)
- Spring Security + JWT
- MySQL (production) / H2 (tests)
- Maven
- Libraries for Excel/PDF export (e.g., Apache POI, iText)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        CLIENTS["Web/Mobile/Postman"]:::clients
    end

    %% Security Layer
    subgraph "Security Layer"
        FILTER["JwtAuthenticationFilter"]:::security
        AUTH_SERVICE["AuthenticationService"]:::security
        JWT_SERVICE["JwtService"]:::security
        USER_DETAILS["UserDetailsServiceImp"]:::security
        AUTH_CONTROLLER["AuthenticationController"]:::controller
        SECURITY_CONFIG["SecurityConfig"]:::security
        AUTH_RESPONSE_DTO["AuthenticationResponse (DTO)"]:::dto
    end

    %% API Layer
    subgraph "API Layer"
        MARKET_CTRL["MarketController"]:::controller
        PRODUCT_CTRL["ProductController"]:::controller
        PURCHASE_CTRL["PurchaseController"]:::controller
        STOCK_CTRL["StockController"]:::controller
    end

    %% Service Layer
    subgraph "Service Layer"
        IMPORT_EXPORT["ImportExportService"]:::service
        MARKET_SVC["MarketService"]:::service
        PRODUCT_SVC["ProductService"]:::service
        PURCHASE_SVC["PurchaseService"]:::service
        STOCK_SVC["StockService"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        MARKET_REPO["MarketRepository"]:::repository
        PRODUCT_REPO["ProductRepository"]:::repository
        PURCHASE_REPO["PurchaseRepository"]:::repository
        STOCK_REPO["StockRepository"]:::repository
        USER_REPO["UserRepository"]:::repository
    end

    %% Database & External
    subgraph "Database & External"
        DB["MySQL Database"]:::database
        EXT_LIB["PDF/Excel Libraries"]:::external
    end

    %% Application Entry & Config
    ENTRY["StockManagementApplication"]:::entry
    APP_CONFIG["application.properties"]:::config
    POM["pom.xml"]:::config

    %% Data Layer DTOs and Entities
    subgraph "Data Layer"
        subgraph "DTOs"
            MARKET_DTO["MarketCreateDto"]:::dto
            PRODUCT_DTO["ProductCreateDto"]:::dto
            PURCHASE_DTO["PurchaseCreateDto"]:::dto
            STOCK_DTO["StockCreateDto"]:::dto
        end
        subgraph "Entities"
            AUDIT["Audit"]:::model
            MARKET_ENTITY["Market"]:::model
            PRODUCT_ENTITY["Product"]:::model
            PURCHASE_ENTITY["Purchase"]:::model
            STOCK_ENTITY["Stock"]:::model
            USER_ENTITY["User"]:::model
        end
        subgraph "Enums"
            CATEGORY["Category"]:::constant
            STATUS["PurchaseStatus"]:::constant
            ROLE["Role"]:::constant
        end
    end

    %% Flows
    CLIENTS -->|Request| FILTER
    FILTER -->|Validate JWT| AUTH_SERVICE
    AUTH_SERVICE -->|Load User| USER_DETAILS
    AUTH_SERVICE -->|Generate/Verify Token| JWT_SERVICE
    FILTER -->|Forward if valid| MARKET_CTRL
    FILTER --> MARKET_CTRL
    FILTER --> PRODUCT_CTRL
    FILTER --> PURCHASE_CTRL
    FILTER --> STOCK_CTRL
    FILTER --> AUTH_CONTROLLER

    AUTH_CONTROLLER -->|Auth APIs| AUTH_SERVICE

    MARKET_CTRL -->|uses| MARKET_SVC
    PRODUCT_CTRL -->|uses| PRODUCT_SVC
    PURCHASE_CTRL -->|uses| PURCHASE_SVC
    STOCK_CTRL -->|uses| STOCK_SVC

    IMPORT_EXPORT -->|uses| EXT_LIB
    IMPORT_EXPORT -->|data via| MARKET_SVC
    IMPORT_EXPORT -->|data via| PRODUCT_SVC
    IMPORT_EXPORT -->|data via| PURCHASE_SVC
    IMPORT_EXPORT -->|data via| STOCK_SVC

    MARKET_SVC -->|CRUD| MARKET_REPO
    PRODUCT_SVC -->|CRUD| PRODUCT_REPO
    PURCHASE_SVC -->|CRUD| PURCHASE_REPO
    STOCK_SVC -->|CRUD| STOCK_REPO

    MARKET_REPO --> DB
    PRODUCT_REPO --> DB
    PURCHASE_REPO --> DB
    STOCK_REPO --> DB
    USER_REPO --> DB

    ENTRY -->|Bootstraps| SECURITY_CONFIG
    ENTRY -->|Loads| APP_CONFIG

    %% Click events
    click POM "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/pom.xml"
    click ENTRY "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/StockManagementApplication.java"
    click APP_CONFIG "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/resources/application.properties"
    click MARKET_CTRL "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/controller/MarketController.java"
    click PRODUCT_CTRL "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/controller/ProductController.java"
    click PURCHASE_CTRL "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/controller/PurchaseController.java"
    click STOCK_CTRL "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/controller/StockController.java"
    click AUTH_CONTROLLER "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/AuthenticationController.java"
    click FILTER "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/JwtAuthenticationFilter.java"
    click JWT_SERVICE "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/JwtService.java"
    click AUTH_SERVICE "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/AuthenticationService.java"
    click SECURITY_CONFIG "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/SecurityConfig.java"
    click USER_DETAILS "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/UserDetailsServiceImp.java"
    click AUTH_RESPONSE_DTO "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/security/AuthenticationResponse.java"
    click IMPORT_EXPORT "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/services/ImportExportService.java"
    click MARKET_SVC "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/services/MarketService.java"
    click PRODUCT_SVC "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/services/ProductService.java"
    click PURCHASE_SVC "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/services/PurchaseService.java"
    click STOCK_SVC "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/services/StockService.java"
    click MARKET_REPO "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/repository/MarketRepository.java"
    click PRODUCT_REPO "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/repository/ProductRepository.java"
    click PURCHASE_REPO "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/repository/PurchaseRepository.java"
    click STOCK_REPO "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/repository/StockRepository.java"
    click USER_REPO "https://github.com/valdetad/stockmanagement/blob/master/StockManagement/src/main/java/com/example/StockManagement/repository/UserRepository.java"

    %% Styles
    classDef clients fill:#f9f,stroke:#333,stroke-width:1px
    classDef security fill:#f96,stroke:#333,stroke-width:1px
    classDef controller fill:#bbf,stroke:#333,stroke-width:1px
    classDef service fill:#7af,stroke:#333,stroke-width:1px
    classDef repository fill:#9cf,stroke:#333,stroke-width:1px
    classDef database fill:#9f9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#fc9,stroke:#333,stroke-width:1px
    classDef entry fill:#ddf,stroke:#333,stroke-width:1px
    classDef config fill:#ffd,stroke:#333,stroke-width:1px
    classDef dto fill:#def,stroke:#333,stroke-width:1px
    classDef model fill:#efe,stroke:#333,stroke-width:1px
    classDef constant fill:#eef,stroke:#333,stroke-width:1px
```
