# doom1817/fridge_guardian architecture

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

- Interactive diagram: https://gitdiagram.com/doom1817/fridge_guardian
- Repository: https://github.com/doom1817/fridge_guardian
- Video tour (about a minute): https://gitdiagram.com/doom1817/fridge_guardian/video

## Overview

Fridge Guardian lets users manage food inventory, track expiry, and use AI to generate recipes from selected ingredients. The main flow is authenticated user → inventory management and expiry monitoring → AI recipe generation → saved recipe and feedback; the dashboard also summarizes consumed and wasted food. The README describes caching, alerts, and visualizations; sampled code confirms the food, authentication, and AI flows, but does not expose every subsystem’s wiring, so those links are omitted where uncertain.

Main entry points: [`src/main/java/com/doom/fg/service/impl/AiServiceImpl.java`](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/AiServiceImpl.java) (AI Service), [`src/main/java/com/doom/fg/controller/FoodApiController.java`](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/FoodApiController.java) (Food API), [`src/main/java/com/doom/fg/controller/AiApiController.java`](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/AiApiController.java) (AI API), [`src/main/java/com/doom/fg/service/impl/FoodItemServiceImpl.java`](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/FoodItemServiceImpl.java) (Food Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and Pages"]
  node_pages["Web Pages"]
  node_food_ui["Food UI<br/>[food_list.js]"]
  node_expiry_ui["Expiry UI<br/>[expiring_alert.js]"]
  node_ai_ui["AI UI<br/>[ai_recipe.js]"]
  node_auth_api["Authentication API"]
  node_jwt["JWT Utilities<br/>[JwtUtil.java]"]
  node_jwt_filter["JWT Filter<br/>[JwtFilter.java]"]
  node_dashboard["Dashboard UI<br/>[index.js]"]
  node_auth_controller_user_service["User Service"]
end

subgraph group_inventory["Food Inventory"]
  node_food_api["Food API"]
  node_food_service["Food Service"]
  node_category_service["Category Service"]
  node_expiry_task["Expiry Scanner"]
end

subgraph group_ai["AI Recipes"]
  node_ai_api["AI API"]
  node_ai_service["AI Service<br/>[AiServiceImpl.java]"]
  node_ai_prompts["Prompt Builder<br/>[AiPrompts.java]"]
  node_ai_engine["AI Engine"]
  node_recipe_service["Recipe Records"]
end

subgraph group_data["Persistence and Cache"]
  node_food_store[("Food Storage")]
  node_category_store[("Category Storage")]
  node_user_store[("User Storage<br/>[UserMapper.java]")]
  node_recipe_store[("Recipe Storage")]
  node_ai_log_store[("AI Log Storage")]
  node_redis[("Redis Cache")]
end

node_user(("User"))
node_llm{{"LLM Provider"}}

node_user -->|"opens"| node_pages
node_user -->|"authenticates"| node_auth_api
node_auth_api -->|"checks or saves"| node_auth_controller_user_service
node_auth_api -->|"issues token"| node_jwt
node_user -->|"manages food"| node_food_ui
node_food_ui -->|"requests inventory"| node_food_api
node_expiry_ui -->|"requests alerts"| node_food_api
node_food_api -->|"queries and updates"| node_food_service
node_food_api -->|"lists categories"| node_category_service
node_food_service -->|"reads and writes"| node_food_store
node_category_service -->|"reads categories"| node_category_store
node_expiry_task -->|"scans expiry"| node_food_service
node_user -->|"views statistics"| node_dashboard
node_dashboard -->|"requests statistics"| node_food_api
node_user -->|"selects ingredients"| node_ai_ui
node_ai_ui -->|"requests recipe"| node_ai_api
node_ai_api -->|"generates or chats"| node_ai_service
node_ai_api -->|"saves AI config"| node_auth_controller_user_service
node_ai_api -->|"queries usage trends"| node_ai_log_store
node_ai_service -->|"loads ingredients"| node_food_service
node_ai_service -->|"builds prompts"| node_ai_prompts
node_ai_service -->|"sends prompt and history"| node_ai_engine
node_ai_engine -.->|"calls completions API"| node_llm
node_ai_service -->|"saves generated recipe"| node_recipe_service
node_recipe_service -->|"reads and writes"| node_recipe_store
node_ai_service -->|"writes call logs"| node_ai_log_store
node_ai_service -->|"reads and writes chat history"| node_redis
node_auth_controller_user_service -->|"reads and writes"| node_user_store
node_jwt_filter -->|"validates token"| node_jwt

click node_pages "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/PageController.java"
click node_food_ui "https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/food_list.js"
click node_expiry_ui "https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/expiring_alert.js"
click node_ai_ui "https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/ai_recipe.js"
click node_auth_api "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/AuthController.java"
click node_jwt "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/util/JwtUtil.java"
click node_jwt_filter "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/security/JwtFilter.java"
click node_food_api "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/FoodApiController.java"
click node_food_service "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/FoodItemServiceImpl.java"
click node_category_service "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/CategoryServiceImpl.java"
click node_expiry_task "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/task/ExpiryAlertTask.java"
click node_dashboard "https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/index.js"
click node_ai_api "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/AiApiController.java"
click node_ai_service "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/AiServiceImpl.java"
click node_ai_prompts "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/util/AiPrompts.java"
click node_ai_engine "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/util/OpenAiCompatibleEngine.java"
click node_recipe_service "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/RecipeRecordServiceImpl.java"
click node_auth_controller_user_service "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/UserServiceImpl.java"
click node_food_store "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/FoodItemMapper.java"
click node_category_store "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/CategoryMapper.java"
click node_user_store "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/UserMapper.java"
click node_recipe_store "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/RecipeRecordMapper.java"
click node_ai_log_store "https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/AiApiLogMapper.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_pages,node_food_ui,node_expiry_ui,node_ai_ui,node_auth_api,node_jwt,node_jwt_filter,node_dashboard,node_auth_controller_user_service,node_user toneBlue
class node_food_api,node_food_service,node_category_service,node_expiry_task toneAmber
class node_ai_api,node_ai_service,node_ai_prompts,node_ai_engine,node_recipe_service toneMint
class node_food_store,node_category_store,node_user_store,node_recipe_store,node_ai_log_store,node_redis toneRose
class node_llm toneIndigo
```

## Components

### Access and Pages

- [Web Pages](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/PageController.java): `src/main/java/com/doom/fg/controller/PageController.java`
- [Food UI](https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/food_list.js): `src/main/resources/static/js/food_list.js`
- [Expiry UI](https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/expiring_alert.js): `src/main/resources/static/js/expiring_alert.js`
- [AI UI](https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/ai_recipe.js): `src/main/resources/static/js/ai_recipe.js`
- [Authentication API](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/AuthController.java): `src/main/java/com/doom/fg/controller/AuthController.java`
- [JWT Utilities](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/util/JwtUtil.java): `src/main/java/com/doom/fg/util/JwtUtil.java`
- [JWT Filter](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/security/JwtFilter.java): `src/main/java/com/doom/fg/security/JwtFilter.java`
- [Dashboard UI](https://github.com/doom1817/fridge_guardian/blob/main/src/main/resources/static/js/index.js): `src/main/resources/static/js/index.js`
- [User Service](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/UserServiceImpl.java): `src/main/java/com/doom/fg/service/impl/UserServiceImpl.java`

### Food Inventory

- [Food API](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/FoodApiController.java): `src/main/java/com/doom/fg/controller/FoodApiController.java`
- [Food Service](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/FoodItemServiceImpl.java): `src/main/java/com/doom/fg/service/impl/FoodItemServiceImpl.java`
- [Category Service](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/CategoryServiceImpl.java): `src/main/java/com/doom/fg/service/impl/CategoryServiceImpl.java`
- [Expiry Scanner](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/task/ExpiryAlertTask.java): `src/main/java/com/doom/fg/task/ExpiryAlertTask.java`

### AI Recipes

- [AI API](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/controller/AiApiController.java): `src/main/java/com/doom/fg/controller/AiApiController.java`
- [AI Service](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/AiServiceImpl.java): `src/main/java/com/doom/fg/service/impl/AiServiceImpl.java`
- [Prompt Builder](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/util/AiPrompts.java): `src/main/java/com/doom/fg/util/AiPrompts.java`
- [AI Engine](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/util/OpenAiCompatibleEngine.java): `src/main/java/com/doom/fg/util/OpenAiCompatibleEngine.java`
- [Recipe Records](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/service/impl/RecipeRecordServiceImpl.java): `src/main/java/com/doom/fg/service/impl/RecipeRecordServiceImpl.java`

### Persistence and Cache

- [Food Storage](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/FoodItemMapper.java): `src/main/java/com/doom/fg/mapper/FoodItemMapper.java`
- [Category Storage](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/CategoryMapper.java): `src/main/java/com/doom/fg/mapper/CategoryMapper.java`
- [User Storage](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/UserMapper.java): `src/main/java/com/doom/fg/mapper/UserMapper.java`
- [Recipe Storage](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/RecipeRecordMapper.java): `src/main/java/com/doom/fg/mapper/RecipeRecordMapper.java`
- [AI Log Storage](https://github.com/doom1817/fridge_guardian/blob/main/src/main/java/com/doom/fg/mapper/AiApiLogMapper.java): `src/main/java/com/doom/fg/mapper/AiApiLogMapper.java`
- **Redis Cache**

### Other components

- **User**
- **LLM Provider**

## Connections

- User → Web Pages: opens
- User → Authentication API: authenticates
- Authentication API → User Service: checks or saves
- Authentication API → JWT Utilities: issues token
- User → Food UI: manages food
- Food UI → Food API: requests inventory
- Expiry UI → Food API: requests alerts
- Food API → Food Service: queries and updates
- Food API → Category Service: lists categories
- Food Service → Food Storage: reads and writes
- Category Service → Category Storage: reads categories
- Expiry Scanner → Food Service: scans expiry
- User → Dashboard UI: views statistics
- Dashboard UI → Food API: requests statistics
- User → AI UI: selects ingredients
- AI UI → AI API: requests recipe
- AI API → AI Service: generates or chats
- AI API → User Service: saves AI config
- AI API → AI Log Storage: queries usage trends
- AI Service → Food Service: loads ingredients
- AI Service → Prompt Builder: builds prompts
- AI Service → AI Engine: sends prompt and history
- AI Engine → LLM Provider: calls completions API
- AI Service → Recipe Records: saves generated recipe
- Recipe Records → Recipe Storage: reads and writes
- AI Service → AI Log Storage: writes call logs
- AI Service → Redis Cache: reads and writes chat history
- User Service → User Storage: reads and writes
- JWT Filter → JWT Utilities: validates token