# fakytop/optify architecture

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

- Interactive diagram: https://gitdiagram.com/fakytop/optify
- Repository: https://github.com/fakytop/optify

## Overview

##### Project type and purpose
- This is a Spring Boot–based REST API whose sole purpose is to compare supermarket prices, manage users, stores, products and simulate shopping carts.
- Key use-cases: user authentication, CRUD on stores/products/categories, import and manual matching of product data, cart simulation, price comparison.

##### File structure
- Top‐level artifacts: Dockerfile (containerization), pom.xml (Maven build), gcloudignore (Google Cloud deployment hints), logs folder.
- src/main/java/com/optify:
- config: application‐wide Spring and CORS settings
- controllers: HTTP endpoints (CartController, ProductController, UserController, etc.)
- domain: JPA entity classes mapping to database tables
- dto: API request/response models decoupled from domain
- facade: coarse‐grained orchestrator combining multiple services
- services: business logic (CartService, ProductService, MatchManagerService, etc.)
- repository: Spring Data JPA interfaces for persistence
- security: JWT filters, API key filter, security configuration
- specifications: criteria builders for dynamic queries
- utilities & utils: helper classes (Console logging, ComparisonUtils)
- src/main/resources: application.properties, logback‐spring.xml
- src/test: unit/integration tests for controllers and services

##### Architectural patterns and principles
- Layered MVC: Controllers → Facade → Services → Repositories → Database
- DTO pattern at the API boundary
- Specification pattern for dynamic filtering
- Stateless, token-based authentication with JWT and API keys
- Dockerized microservice, ready for cloud deployment

##### Main components and interactions
a. Components:
- Client (Web/Mobile/UIs or API consumers)
- API Gateway or Load Balancer (optional entry point)
- Spring Boot App subdivided into:
- API Layer (Controllers + DTOs)
- Facade Layer
- Business Layer (Services)
- Persistence Layer (Repositories)
- Relational Database (PostgreSQL/MySQL)
- Authentication subsystem (JWT provider, API key store)
- External sources (file imports for manual matching)
b. Interactions:
1. Client sends HTTP request → passes through API Key/JWT filters
2. Spring MVC routes to appropriate Controller → maps payload to DTO
3. Controller calls Facade (if present) or directly Service
4. Service runs business logic, uses Specification classes for queries
5. Service invokes Repository → executes SQL on Database
6. Response assembled into DTO → returned to Client
7. DataImportService reads files → invokes ProductService/ManualMatchService → persists via Repositories
c. Technologies:
- Spring Boot, Spring Web MVC, Spring Data JPA (Hibernate), Spring Security (JWT)
- Maven, Docker, Logback
- (Optional) Google Cloud Run/App Engine

##### Detailed call sequence (optional inset)
- A sample path for “Compare Cart Prices”:
Client → JWT Filter → CartController → Facade → MatchManagerService → ProductService → ProductRepository → Database → up through layers → Response.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client"
        Client["Client (Web/Mobile)"]:::external
    end

    subgraph "Spring Boot Application"
        AppApplication["AppApplication\n(Spring Boot Entry)"]:::external
        CorsConfig["CorsConfig\n(Spring & CORS Settings)"]:::external
    end

    subgraph "Security Filters"
        ApiKeyFilter["API Key Filter"]:::security
        JwtFilter["JWT Request Filter"]:::security
    end

    subgraph "Controllers (API Layer)"
        CartController["CartController\nSpring MVC"]:::controller
        ProductController["ProductController\nSpring MVC"]:::controller
        UserController["UserController\nSpring MVC"]:::controller
        StoreController["StoreController\nSpring MVC"]:::controller
        ManualMatchController["ManualMatchController\nSpring MVC"]:::controller
    end

    subgraph "Facade Layer"
        Facade["Facade\nCoarse-grained Orchestration"]:::facade
    end

    subgraph "Service Layer"
        CartService["CartService"]:::service
        ProductService["ProductService"]:::service
        MatchManagerService["MatchManagerService"]:::service
        ManualMatchService["ManualMatchService"]:::service
        DataImportService["DataImportService"]:::service
        StoreService["StoreService"]:::service
        CategoryService["CategoryService"]:::service
        UserService["UserService"]:::service
        DiscardReferenceService["DiscardReferenceService"]:::service
        ProductMergeService["ProductMergeService"]:::service
        StoreProductService["StoreProductService"]:::service
    end

    subgraph "Repository Layer"
        Repositories["Repositories\nSpring Data JPA Interfaces"]:::repo
    end

    Database["Relational Database\n(PostgreSQL/MySQL)"]:::db

    subgraph "External Resources"
        FileStorage["External File Storage / Import"]:::external
    end

    %% Connections
    Client -->|HTTP Request| AppApplication
    AppApplication --> CorsConfig
    CorsConfig --> ApiKeyFilter
    ApiKeyFilter --> JwtFilter
    JwtFilter --> CartController
    JwtFilter --> ProductController
    JwtFilter --> UserController
    JwtFilter --> StoreController
    JwtFilter --> ManualMatchController

    CartController -->|calls| Facade
    ProductController -->|calls| Facade
    UserController -->|calls| Facade
    StoreController -->|calls| Facade
    ManualMatchController -->|calls| Facade

    Facade --> CartService
    Facade --> ProductService
    Facade --> MatchManagerService
    Facade --> ManualMatchService
    Facade --> DataImportService
    Facade --> StoreService
    Facade --> CategoryService
    Facade --> UserService
    Facade --> DiscardReferenceService
    Facade --> ProductMergeService
    Facade --> StoreProductService

    CartService --> Repositories
    ProductService --> Repositories
    MatchManagerService --> Repositories
    ManualMatchService --> Repositories
    DataImportService --> FileStorage
    StoreService --> Repositories
    CategoryService --> Repositories
    UserService --> Repositories
    DiscardReferenceService --> Repositories
    ProductMergeService --> Repositories
    StoreProductService --> Repositories

    Repositories -->|SQL Queries| Database

    %% Click Events
    click AppApplication "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/AppApplication.java"
    click CorsConfig "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/config/CorsConfig.java"
    click CartController "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/controllers/CartController.java"
    click ProductController "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/controllers/ProductController.java"
    click UserController "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/controllers/UserController.java"
    click StoreController "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/controllers/StoreController.java"
    click ManualMatchController "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/controllers/ManualMatchController.java"
    click Facade "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/facade/Facade.java"
    click CartService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/CartService.java"
    click ProductService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/ProductService.java"
    click MatchManagerService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/MatchManagerService.java"
    click ManualMatchService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/ManualMatchService.java"
    click DataImportService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/DataImportService.java"
    click StoreService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/StoreService.java"
    click CategoryService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/CategoryService.java"
    click UserService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/UserService.java"
    click DiscardReferenceService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/DiscardReferenceService.java"
    click ProductMergeService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/ProductMergeService.java"
    click StoreProductService "https://github.com/fakytop/optify/blob/master/src/main/java/com/optify/services/StoreProductService.java"
    click Repositories "https://github.com/fakytop/optify/tree/master/src/main/java/com/optify/repository/"
    click FileStorage "https://github.com/fakytop/optify/tree/master/src/main/resources/"

    %% Styles
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef security fill:#F08080,stroke:#333,stroke-width:1px
    classDef controller fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef facade fill:#FFD700,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef repo fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#D3D3D3,stroke:#333,stroke-width:1px
```
