# xwasnotdeclared/be_cooking architecture

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

- Interactive diagram: https://gitdiagram.com/xwasnotdeclared/be_cooking
- Repository: https://github.com/xwasnotdeclared/be_cooking

## Overview

1. **Overall shape**: This is a **single Spring Boot monolith** organized in the classic **Controller → Service → Repository → JPA Entity** style. The backend is the system of record for recipes, users, orders, wallets, search indexes, notifications, and AI-related metadata.

2. **API surface is split by audience**: Controllers are grouped into:
   - `controller/pub` for public/auth/AI/upload endpoints,
   - domain controllers for recipes, carts, comments, orders, payments, etc.,
   - `controller/admin` for moderation and admin dashboards.
   This separation is a useful boundary for an architecture diagram.

3. **Core content domain**: The main business domain is a recipe platform built around `Recipe`, `Ingredient`, `Step`, `Category`, `Tag`, `Collection`, `Comment`, `RecipeLike`, `UserFollow`, and related join entities. DTOs and mappers sit between the HTTP layer and persistence layer to keep the API contracts separate from entities.

4. **Social and engagement flows**: Recipe creation, updates, likes, comments, follows, and tag/category changes emit domain events such as `RecipeCreatedEvent`, `RecipeUpdatedEvent`, `RecipeCommentedEvent`, and `UserFollowedEvent`. These are handled by listeners that update notifications, indexes, or derived state without coupling the controllers directly to those side effects.

5. **Authentication and security boundary**: Security is implemented with **Spring Security + JWT**. The security layer includes a JWT filter, user-details service, refresh-token support, and auth-related DTOs. `AuthController` and `UserController` are the public entry points for login, registration, reset password, and profile management.

6. **AI / RAG subsystem**: The repo has a distinct AI path with `AIController`, `ChatBotController`, `ChatBotService`, `ToolService`, `RecipeEnrichmentService`, and chatbot tools under `tools_chatbot`. The configuration classes and the README indicate integration with **Groq LLMs** and **Pinecone** for vector search / RAG. This subsystem answers cooking questions, suggests recipes from ingredients, and supports image-based ingredient understanding.

7. **Search and retrieval**: Recipe search is not just relational filtering. There is a dedicated search stack with `SearchService`, `MeiliRecipeService`, `RecipeSearchIndex`, and `PineconeClientConfig`. The architecture suggests a two-path retrieval model: standard DB queries for normal browsing and vector/semantic retrieval for AI-assisted discovery.

8. **Commerce and fulfillment**: The platform also supports a marketplace-like flow: cart, buy-now, buyer and seller order controllers/services, dish orders, payment orders, wallet transactions, seller wallets, package upgrades, and withdrawals. `VNPayConfig` shows that external payment processing is part of the order flow, with wallet settlement handled inside the backend.

9. **Media and uploads**: File handling is centralized through `UploadController`, `UploadFileService`, and a `LocalFileUploadService` implementation. Uploaded assets are stored in the repo’s `static_resource` area, so media storage is an explicit subsystem rather than being embedded in the recipe domain.

10. **Persistence and derived data**: Persistence is primarily through Spring Data repositories over MySQL. The repo also includes projection DTOs and stats DTOs for dashboards, recipe analytics, and leaderboards. That indicates read-optimized queries for reporting alongside the transactional entities.

11. **Background processing and consistency**: There is a scheduler (`RecipeSyncScheduler`) and an `OutBoxEvent` model/repository, which together point to asynchronous synchronization patterns. The likely architectural purpose is to keep derived systems such as search indexes and notifications consistent with the main relational data store.

12. **Client applications in the repo**: The repository contains two separate frontend clients:
   - `recipe-app`: a **React + Vite + TypeScript** web client,
   - `recipe`: an **Expo/React Native** client structure.
   The README’s frontend notes are older, so the tree is the better source for the current client layout.

13. **Operational bootstrap**: `DataInitializer`, `AppProperties`, `JwtProperties`, `UploadProperties`, and `OpenApiConfig` show that startup wiring is important: seed data, environment-driven configuration, Swagger/OpenAPI docs, and integration credentials are all part of deployment-time architecture.

14. **Main external dependencies**: The backend materially depends on **MySQL**, **Pinecone**, **Groq/LLM APIs**, **VNPay**, and email/OTP support. These external services shape the system boundaries more than the UI does, especially for AI, payments, and notification flows.

Main entry points: [`cooking/src/main/java/com/example/cooking/controller/pub`](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller/pub) (Public API), [`cooking/src/main/java/com/example/cooking/repository`](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/repository) (Repositories), [`cooking/src/main/java/com/example/cooking/controller`](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller) (Domain API), [`cooking/src/main/java/com/example/cooking/service`](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service) (AI & Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Spring Boot backend"]
  node_app(("Cooking App<br/>spring boot entrypoint"))
  node_api_pub["Public API<br/>public controllers"]
  node_api_domain["Domain API<br/>domain controllers"]
  node_api_admin["Admin API<br/>admin controllers"]
  node_auth["Security<br/>jwt auth"]
  node_services_core["Core Services<br/>business services"]
  node_services_engagement["Engagement<br/>social services"]
  node_services_commerce["Commerce<br/>order and payment services"]
  node_services_ai["AI & Search<br/>ai retrieval services"]
  node_uploads["Uploads<br/>file service"]
  node_events(("Domain Events<br/>event model"))
  node_listeners["Event Listeners<br/>async handlers"]
  node_models[("Domain Models<br/>jpa entities")]
  node_repos["Repositories<br/>spring data jpa"]
  node_dto_map["DTOs & Mappers<br/>api contracts"]
  node_config["Config & Bootstrap<br/>startup wiring"]
  node_scheduler["Scheduler<br/>background jobs"]
end

subgraph group_clients["Client apps"]
  node_client_web["Web Client<br/>react vite ts"]
  node_client_mobile["Mobile App<br/>expo react native"]
end

subgraph group_external["External systems"]
  node_db[("MySQL<br/>relational database")]
  node_llm(("Groq LLM<br/>ai api"))
  node_vector[("Pinecone<br/>vector db")]
  node_payment(("VNPay<br/>payment gateway"))
end

node_app -->|"loads"| node_config
node_app -->|"secures"| node_auth
node_app -->|"exposes"| node_api_pub
node_app -->|"exposes"| node_api_domain
node_app -->|"exposes"| node_api_admin
node_api_pub -->|"uses"| node_dto_map
node_api_domain -->|"uses"| node_dto_map
node_api_admin -->|"uses"| node_dto_map
node_api_pub -->|"calls"| node_services_core
node_api_domain -->|"calls"| node_services_core
node_api_domain -->|"calls"| node_services_engagement
node_api_domain -->|"calls"| node_services_commerce
node_api_pub -->|"calls"| node_services_ai
node_services_core -->|"persists"| node_models
node_services_engagement -->|"persists"| node_models
node_services_commerce -->|"persists"| node_models
node_services_ai -->|"reads"| node_models
node_services_core -->|"uses"| node_repos
node_services_engagement -->|"uses"| node_repos
node_services_commerce -->|"uses"| node_repos
node_services_ai -->|"uses"| node_repos
node_services_ai -.->|"integrates"| node_llm
node_services_ai -.->|"integrates"| node_vector
node_services_commerce -.->|"integrates"| node_payment
node_uploads -->|"served by"| node_api_pub
node_uploads -->|"configured by"| node_config
node_events -->|"handled by"| node_listeners
node_services_core -->|"emits"| node_events
node_services_engagement -->|"emits"| node_events
node_listeners -->|"updates"| node_services_engagement
node_listeners -->|"writes"| node_repos
node_scheduler -->|"syncs"| node_repos
node_scheduler -.->|"refreshes"| node_services_ai
node_config -->|"connects"| node_db
node_repos -->|"reads/writes"| node_db
node_client_web -->|"consumes"| node_api_pub
node_client_web -->|"consumes"| node_api_domain
node_client_mobile -->|"consumes"| node_api_pub

click node_app "https://github.com/xwasnotdeclared/be_cooking/blob/main/cooking/src/main/java/com/example/cooking/CookingApplication.java"
click node_api_pub "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller/pub"
click node_api_domain "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller"
click node_api_admin "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller/admin"
click node_auth "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/security"
click node_services_core "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service"
click node_services_engagement "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service"
click node_services_commerce "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service"
click node_services_ai "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service"
click node_uploads "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service/impl"
click node_events "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/event"
click node_listeners "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/listener"
click node_models "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/model"
click node_repos "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/repository"
click node_dto_map "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/dto"
click node_config "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/config"
click node_scheduler "https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/cheduler"
click node_client_web "https://github.com/xwasnotdeclared/be_cooking/tree/main/recipe-app"
click node_client_mobile "https://github.com/xwasnotdeclared/be_cooking/tree/main/recipe"

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_api_pub,node_api_domain,node_api_admin,node_auth,node_services_core,node_services_engagement,node_services_commerce,node_services_ai,node_uploads,node_events,node_listeners,node_models,node_repos,node_dto_map,node_config,node_scheduler toneBlue
class node_client_web,node_client_mobile toneAmber
class node_db,node_llm,node_vector,node_payment toneMint
```

## Components

### Spring Boot backend

Monolithic backend with API, domain, persistence, security, AI, and async workflows.

- [Cooking App](https://github.com/xwasnotdeclared/be_cooking/blob/main/cooking/src/main/java/com/example/cooking/CookingApplication.java): spring boot entrypoint · Main backend application bootstrap and wiring. · `cooking/src/main/java/com/example/cooking/CookingApplication.java`
- [Public API](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller/pub): public controllers · Auth, AI, upload, and other public-facing endpoints. · `cooking/src/main/java/com/example/cooking/controller/pub`
- [Domain API](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller): domain controllers · Recipe, cart, comments, orders, payments, search, and profile endpoints. · `cooking/src/main/java/com/example/cooking/controller`
- [Admin API](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/controller/admin): admin controllers · Moderation and dashboard endpoints for administrators. · `cooking/src/main/java/com/example/cooking/controller/admin`
- [Security](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/security): jwt auth · JWT, Spring Security, user details, and request filtering. · `cooking/src/main/java/com/example/cooking/security`
- [Core Services](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service): business services · Recipe, user, social, category, tag, ingredient, and collection orchestration. · `cooking/src/main/java/com/example/cooking/service`
- [Engagement](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service): social services · Comments, likes, follows, notifications, and derived engagement flows. · `cooking/src/main/java/com/example/cooking/service`
- [Commerce](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service): order and payment services · Cart, buyer/seller orders, payments, wallets, withdrawals, and upgrades. · `cooking/src/main/java/com/example/cooking/service`
- [AI & Search](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service): ai retrieval services · Chatbot, tool execution, enrichment, semantic search, and vector data handling. · `cooking/src/main/java/com/example/cooking/service`
- [Uploads](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/service/impl): file service · Centralized file upload abstraction and local storage implementation. · `cooking/src/main/java/com/example/cooking/service/impl`
- [Domain Events](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/event): event model · Recipe, category, tag, and follow events emitted by core workflows. · `cooking/src/main/java/com/example/cooking/event`
- [Event Listeners](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/listener): async handlers · Notification, index, and derived-state handlers for domain events. · `cooking/src/main/java/com/example/cooking/listener`
- [Domain Models](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/model): jpa entities · Recipe, user, order, wallet, search index, notification, and relationship entities. · `cooking/src/main/java/com/example/cooking/model`
- [Repositories](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/repository): spring data jpa · Persistence layer for transactional data, search indexes, and reporting reads. · `cooking/src/main/java/com/example/cooking/repository`
- [DTOs & Mappers](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/dto): api contracts · Request/response DTOs, projections, and mappers between HTTP and persistence. · `cooking/src/main/java/com/example/cooking/dto`
- [Config & Bootstrap](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/config): startup wiring · App properties, OpenAPI, data seeding, payment, AI, upload, and web config. · `cooking/src/main/java/com/example/cooking/config`
- [Scheduler](https://github.com/xwasnotdeclared/be_cooking/tree/main/cooking/src/main/java/com/example/cooking/cheduler): background jobs · Periodic synchronization for derived systems. · `cooking/src/main/java/com/example/cooking/cheduler`

### Client apps

Web and mobile frontends included in the repository.

- [Web Client](https://github.com/xwasnotdeclared/be_cooking/tree/main/recipe-app): react vite ts · React web frontend for browsing and creating recipes. · `recipe-app`
- [Mobile App](https://github.com/xwasnotdeclared/be_cooking/tree/main/recipe): expo react native · Expo-based mobile client structure. · `recipe`

### External systems

Third-party and infrastructure dependencies shaped by backend integrations.

- **MySQL**: relational database · Primary system of record for backend persistence.
- **Groq LLM**: ai api · Large language model provider used by chatbot and AI features.
- **Pinecone**: vector db · Vector search backend for semantic retrieval and RAG.
- **VNPay**: payment gateway · External payment processing and transaction confirmation.

## Connections

- Cooking App → Config & Bootstrap: loads · Bootstraps application settings, seed data, and integrations.
- Cooking App → Security: secures · Applies security configuration to request processing.
- Cooking App → Public API: exposes · Publishes public endpoints.
- Cooking App → Domain API: exposes · Publishes domain endpoints.
- Cooking App → Admin API: exposes · Publishes admin endpoints.
- Public API → DTOs & Mappers: uses · Consumes request and response contracts.
- Domain API → DTOs & Mappers: uses · Maps between HTTP payloads and domain data.
- Admin API → DTOs & Mappers: uses · Uses dashboard DTOs and projections.
- Public API → Core Services: calls · Delegates public recipe and profile actions.
- Domain API → Core Services: calls · Delegates core recipe and catalog operations.
- Domain API → Engagement: calls · Handles comments, likes, follows, and notifications.
- Domain API → Commerce: calls · Handles carts, orders, payments, and wallets.
- Public API → AI & Search: calls · Routes chatbot and AI-assisted retrieval requests.
- Core Services → Domain Models: persists · Reads and writes recipe and catalog entities.
- Engagement → Domain Models: persists · Updates social and notification entities.
- Commerce → Domain Models: persists · Updates order, payment, and wallet entities.
- AI & Search → Domain Models: reads · Uses recipe and search index data for retrieval.
- Core Services → Repositories: uses · Coordinates persistence through repositories.
- Engagement → Repositories: uses · Stores likes, comments, follows, and notifications.
- Commerce → Repositories: uses · Stores commerce and wallet state.
- AI & Search → Repositories: uses · Reads search and content data.
- AI & Search → Groq LLM: integrates · Delegates chatbot reasoning and generation.
- AI & Search → Pinecone: integrates · Performs semantic search and RAG retrieval.
- Commerce → VNPay: integrates · Processes payment and settlement flows.
- Uploads → Public API: served by · Upload endpoints expose file ingestion.
- Uploads → Config & Bootstrap: configured by · Uses upload properties and storage settings.
- Domain Events → Event Listeners: handled by · Event listeners react to published domain events.
- Core Services → Domain Events: emits · Publishes recipe and catalog change events.
- Engagement → Domain Events: emits · Publishes social interaction events.
- Event Listeners → Engagement: updates · Creates notifications and derived engagement state.
- Event Listeners → Repositories: writes · Persists event-driven side effects and indexes.
- Scheduler → Repositories: syncs · Coordinates periodic consistency work.
- Scheduler → AI & Search: refreshes · Supports search/index synchronization jobs.
- Config & Bootstrap → MySQL: connects · Configures primary relational persistence.
- Repositories → MySQL: reads/writes · Implements the system of record.
- Web Client → Public API: consumes · Uses public backend APIs.
- Web Client → Domain API: consumes · Uses recipe and commerce APIs.
- Mobile App → Public API: consumes · Uses public backend APIs.
