anufrievalex2006/kosmetichka-shop

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.