# anufrievalex2006/kosmetichka-shop architecture

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

- Interactive diagram: https://gitdiagram.com/anufrievalex2006/kosmetichka-shop
- Repository: https://github.com/anufrievalex2006/kosmetichka-shop

## Overview

#### 1. System Purpose and Deployment
KoSmetichka is a full-stack cosmetics-store system: public catalog/cart/account flows plus an administrative inventory/content console. Docker Compose deploys the Next.js frontend, Spring Boot API, PostgreSQL, and MinIO. Primary deployment/build files: `docker-compose.yml`, `backend/Dockerfile`, `frontend/Dockerfile`.

#### 2. Runtime Entry Points
The backend starts as a Java Spring Boot application at `backend/src/main/java/com/kosmetichka/backend/BackendApplication.java`; its HTTP API is exposed through Spring controllers. The frontend is a Next.js App Router application rooted at `frontend/src/app/layout.tsx`, with public routes such as `frontend/src/app/page.tsx` and admin routes under `frontend/src/app/admin/`. Swagger/OpenAPI configuration is in `backend/src/main/java/com/kosmetichka/backend/config/OpenApiConfig.java`.

#### 3. Backend API and Domain Boundary
Controllers are the REST boundary; request/response DTOs isolate clients from persistence entities. Services implement application workflows, repositories persist JPA models, and mappers convert entities to API responses. Product catalog management centers on:
- `backend/src/main/java/com/kosmetichka/backend/controllers/ProductController.java`
- `backend/src/main/java/com/kosmetichka/backend/services/ProductService.java`
- `backend/src/main/java/com/kosmetichka/backend/models/api/Product.java`

Categories, brands, and dynamic attributes define product structure and filtering:
- `backend/src/main/java/com/kosmetichka/backend/models/api/Category.java`
- `backend/src/main/java/com/kosmetichka/backend/models/api/Attribute.java`
- `backend/src/main/java/com/kosmetichka/backend/dtos/requests/filter/ProductSpecification.java`

#### 4. Commerce, Content, and Operations
Cart state is server-side and represented as carts with positions; checkout-related communication is delegated to email services. Relevant paths: `backend/src/main/java/com/kosmetichka/backend/services/CartService.java`, `backend/src/main/java/com/kosmetichka/backend/models/api/CartPosition.java`, `backend/src/main/java/com/kosmetichka/backend/services/EmailService.java`.

Content cards support news/promotions, while appeals/contact flows cover client questions and supplier requests:
- `backend/src/main/java/com/kosmetichka/backend/services/ContentCardService.java`
- `backend/src/main/java/com/kosmetichka/backend/services/AppealService.java`
- `backend/src/main/java/com/kosmetichka/backend/controllers/ContactController.java`

Administrative counts and statistics are separate dashboard-oriented read flows: `backend/src/main/java/com/kosmetichka/backend/services/AdminDashboardCountService.java`.

#### 5. Identity, Authorization, and Recovery
Spring Security protects API access using JWT access/refresh tokens. The request security path is configuration → JWT filter → principal/user-details lookup → controller authorization:
- `backend/src/main/java/com/kosmetichka/backend/config/SecurityConfig.java`
- `backend/src/main/java/com/kosmetichka/backend/security/JwtFilter.java`
- `backend/src/main/java/com/kosmetichka/backend/services/AuthService.java`

Users, roles, password-reset tokens, and email delivery underpin registration, login, profile management, and reset-password workflows: `backend/src/main/java/com/kosmetichka/backend/models/api/User.java`, `backend/src/main/java/com/kosmetichka/backend/services/PasswordResetService.java`.

#### 6. Frontend Layers and Request Flow
Next route pages compose views/widgets; feature modules coordinate use cases; repository implementations call the backend through Axios; domain interfaces and DTOs form the frontend’s API boundary. Core paths:
- `frontend/src/data/api/axiosInstance.ts`
- `frontend/src/data/repos/ProductRepo.ts`
- `frontend/src/features/cart.ts`

TanStack Query is provided application-wide through `frontend/src/shared/providers/QueryProvider.tsx`. Public catalog/product pages consume catalog and product widgets, while admin pages compose separate management widgets:
- `frontend/src/app/catalog/page.tsx`
- `frontend/src/widgets/catalog/CatalogMain.tsx`
- `frontend/src/widgets/admin/categoryDetails/products/AdminProductsMain.tsx`

#### 7. Cross-Service Integration Boundaries
PostgreSQL is accessed through Spring Data JPA repositories, e.g. `backend/src/main/java/com/kosmetichka/backend/repos/ProductRepo.java`. MinIO stores product/content/user files behind `FileStorageService` and `FileController`: `backend/src/main/java/com/kosmetichka/backend/services/FileStorageService.java`. JavaMailSender-backed email is an external delivery boundary for password resets and order receipts. The frontend also exposes Next route handlers for authentication cookie/token handling, including `frontend/src/app/api/auth/login/route.ts` and `frontend/src/app/api/auth/authCookies.ts`.

Main entry points: [`backend/src/main/java/com/kosmetichka/backend/BackendApplication.java`](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/BackendApplication.java) (Spring Boot API), [`docker-compose.yml`](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/docker-compose.yml) (Docker Compose), [`frontend/src/app/layout.tsx`](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/layout.tsx) (App routes), [`backend/src/main/java/com/kosmetichka/backend/services/ProductService.java`](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/ProductService.java) (Application services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_next_routes["App routes<br/>Next.js App Router<br/>[layout.tsx]"]
  node_catalog_page["Catalog page<br/>public route<br/>[page.tsx]"]
  node_admin_products["Admin product management<br/>admin widget"]
  node_catalog_widget["Catalog widget<br/>UI widget<br/>[CatalogMain.tsx]"]
  node_query_provider["TanStack Query provider<br/>client state<br/>[QueryProvider.tsx]"]
  node_frontend_features["Feature modules<br/>use cases<br/>[cart.ts]"]
  node_frontend_repos["Repository clients<br/>data access<br/>[ProductRepo.ts]"]
  node_axios["Axios API client<br/>HTTP client<br/>[axiosInstance.ts]"]
  node_auth_handlers["Auth route handlers<br/>Next route handlers<br/>[route.ts]"]
end

subgraph group_backend["Spring Boot API"]
  node_api_entry["Spring Boot API<br/>application entry"]
  node_security["JWT security path<br/>security middleware<br/>[JwtFilter.java]"]
  node_controllers["REST controllers<br/>API boundary"]
  node_services["Application services<br/>domain workflows"]
  node_auth_service["Identity &amp; recovery<br/>auth service<br/>[AuthService.java]"]
  node_repositories["JPA repositories<br/>persistence layer<br/>[ProductRepo.java]"]
  node_file_storage["File storage service<br/>object storage adapter"]
  node_openapi["OpenAPI / Swagger<br/>API documentation<br/>[OpenApiConfig.java]"]
end

subgraph group_integrations["Data &amp; external services"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_minio[("MinIO<br/>object storage")]
  node_email["Email delivery<br/>external mail service"]
end

node_compose{{"Docker Compose<br/>deployment<br/>[docker-compose.yml]"}}

node_compose -->|"deploys"| node_next_routes
node_compose -->|"deploys"| node_api_entry
node_compose -->|"deploys"| node_postgres
node_compose -->|"deploys"| node_minio
node_next_routes -->|"includes"| node_catalog_page
node_catalog_page -->|"composes"| node_catalog_widget
node_next_routes -->|"serves admin routes"| node_admin_products
node_next_routes -->|"provides"| node_query_provider
node_catalog_widget -->|"uses"| node_frontend_features
node_admin_products -->|"uses"| node_frontend_features
node_frontend_features -->|"loads and mutates data"| node_frontend_repos
node_frontend_repos -->|"uses"| node_axios
node_auth_handlers -->|"auth API calls"| node_api_entry
node_axios -->|"REST requests"| node_api_entry
node_api_entry -->|"applies"| node_security
node_security -->|"authorizes"| node_controllers
node_controllers -->|"delegates workflows"| node_services
node_controllers -->|"auth endpoints"| node_auth_service
node_services -->|"persists domain data"| node_repositories
node_repositories -->|"Spring Data JPA"| node_postgres
node_services -->|"manages files"| node_file_storage
node_file_storage -->|"stores objects"| node_minio
node_services -->|"checkout communication"| node_email
node_auth_service -->|"password resets"| node_email
node_api_entry -.->|"publishes API docs"| node_openapi

click node_compose "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/docker-compose.yml"
click node_next_routes "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/layout.tsx"
click node_catalog_page "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/catalog/page.tsx"
click node_admin_products "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/widgets/admin/categoryDetails/products/AdminProductsMain.tsx"
click node_catalog_widget "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/widgets/catalog/CatalogMain.tsx"
click node_query_provider "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/shared/providers/QueryProvider.tsx"
click node_frontend_features "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/features/cart.ts"
click node_frontend_repos "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/data/repos/ProductRepo.ts"
click node_axios "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/data/api/axiosInstance.ts"
click node_auth_handlers "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/api/auth/login/route.ts"
click node_api_entry "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/BackendApplication.java"
click node_security "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/security/JwtFilter.java"
click node_controllers "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/controllers/ProductController.java"
click node_services "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/ProductService.java"
click node_auth_service "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/AuthService.java"
click node_repositories "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/repos/ProductRepo.java"
click node_file_storage "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/FileStorageService.java"
click node_openapi "https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/config/OpenApiConfig.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_next_routes,node_catalog_page,node_admin_products,node_catalog_widget,node_query_provider,node_frontend_features,node_frontend_repos,node_axios,node_auth_handlers toneBlue
class node_api_entry,node_security,node_controllers,node_services,node_auth_service,node_repositories,node_file_storage,node_openapi toneAmber
class node_postgres,node_minio,node_email toneMint
class node_compose toneNeutral
```

## Components

### Next.js frontend

- [App routes](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/layout.tsx): Next.js App Router · Public catalog/account and administrative page entry points. · `frontend/src/app/layout.tsx`
- [Catalog page](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/catalog/page.tsx): public route · `frontend/src/app/catalog/page.tsx`
- [Admin product management](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/widgets/admin/categoryDetails/products/AdminProductsMain.tsx): admin widget · `frontend/src/widgets/admin/categoryDetails/products/AdminProductsMain.tsx`
- [Catalog widget](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/widgets/catalog/CatalogMain.tsx): UI widget · `frontend/src/widgets/catalog/CatalogMain.tsx`
- [TanStack Query provider](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/shared/providers/QueryProvider.tsx): client state · `frontend/src/shared/providers/QueryProvider.tsx`
- [Feature modules](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/features/cart.ts): use cases · Coordinates cart and other client workflows. · `frontend/src/features/cart.ts`
- [Repository clients](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/data/repos/ProductRepo.ts): data access · Maps frontend use cases to backend API calls. · `frontend/src/data/repos/ProductRepo.ts`
- [Axios API client](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/data/api/axiosInstance.ts): HTTP client · `frontend/src/data/api/axiosInstance.ts`
- [Auth route handlers](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/frontend/src/app/api/auth/login/route.ts): Next route handlers · Handles authentication cookies and tokens. · `frontend/src/app/api/auth/login/route.ts`

### Spring Boot API

- [Spring Boot API](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/BackendApplication.java): application entry · `backend/src/main/java/com/kosmetichka/backend/BackendApplication.java`
- [JWT security path](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/security/JwtFilter.java): security middleware · Security configuration and filter authenticate requests before authorization. · `backend/src/main/java/com/kosmetichka/backend/security/JwtFilter.java`
- [REST controllers](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/controllers/ProductController.java): API boundary · DTO-based HTTP endpoints for catalog, commerce, content, and administration. · `backend/src/main/java/com/kosmetichka/backend/controllers/ProductController.java`
- [Application services](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/ProductService.java): domain workflows · Implements product, cart, content, appeal, and dashboard workflows. · `backend/src/main/java/com/kosmetichka/backend/services/ProductService.java`
- [Identity & recovery](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/AuthService.java): auth service · Issues JWTs and supports user and password-reset flows. · `backend/src/main/java/com/kosmetichka/backend/services/AuthService.java`
- [JPA repositories](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/repos/ProductRepo.java): persistence layer · Persists products, users, carts, content, and related models. · `backend/src/main/java/com/kosmetichka/backend/repos/ProductRepo.java`
- [File storage service](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/services/FileStorageService.java): object storage adapter · Stores product, content, and user files. · `backend/src/main/java/com/kosmetichka/backend/services/FileStorageService.java`
- [OpenAPI / Swagger](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/backend/src/main/java/com/kosmetichka/backend/config/OpenApiConfig.java): API documentation · `backend/src/main/java/com/kosmetichka/backend/config/OpenApiConfig.java`

### Data & external services

- **PostgreSQL**: relational database
- **MinIO**: object storage
- **Email delivery**: external mail service · Delivers password resets and checkout communications.

### Other components

- [Docker Compose](https://github.com/anufrievalex2006/kosmetichka-shop/blob/main/docker-compose.yml): deployment · Deploys frontend, API, PostgreSQL, and MinIO. · `docker-compose.yml`

## Connections

- Docker Compose → App routes: deploys
- Docker Compose → Spring Boot API: deploys
- Docker Compose → PostgreSQL: deploys
- Docker Compose → MinIO: deploys
- App routes → Catalog page: includes
- Catalog page → Catalog widget: composes
- App routes → Admin product management: serves admin routes
- App routes → TanStack Query provider: provides
- Catalog widget → Feature modules: uses
- Admin product management → Feature modules: uses
- Feature modules → Repository clients: loads and mutates data
- Repository clients → Axios API client: uses
- Auth route handlers → Spring Boot API: auth API calls
- Axios API client → Spring Boot API: REST requests
- Spring Boot API → JWT security path: applies
- JWT security path → REST controllers: authorizes
- REST controllers → Application services: delegates workflows
- REST controllers → Identity & recovery: auth endpoints
- Application services → JPA repositories: persists domain data
- JPA repositories → PostgreSQL: Spring Data JPA
- Application services → File storage service: manages files
- File storage service → MinIO: stores objects
- Application services → Email delivery: checkout communication
- Identity & recovery → Email delivery: password resets
- Spring Boot API → OpenAPI / Swagger: publishes API docs