# yasen-ab/homeychefpt architecture

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

- Interactive diagram: https://gitdiagram.com/yasen-ab/homeychefpt
- Repository: https://github.com/yasen-ab/homeychefpt

## Overview

1. **Overall shape**
   - HomeyChef is a **single Node.js/Express backend** that also serves its own browser UI from `backend/views`.
   - The system is organized as a **layered monolith**: client pages and scripts call Express routes, controllers orchestrate requests, services handle non-trivial business logic, and Sequelize models persist to MySQL.

2. **Entry points and bootstrapping**
   - `backend/server.js` is the runtime entry point.
   - `backend/config/database.js` configures the Sequelize/MySQL connection, while `backend/config/syncDatabase.js` suggests schema sync/initialization support.
   - The app likely mounts route modules by domain and exposes both API endpoints and static view assets.

3. **Presentation layer**
   - The browser UI lives under `backend/views` as HTML/CSS/JS, not as a separate SPA build system.
   - There are distinct screens for **login/register**, **user dashboard**, **chef dashboard**, **admin dashboard**, **menu/dishes**, **cart**, **orders**, **favorites**, **notifications**, **statistics**, and password recovery.
   - Frontend JavaScript files call backend endpoints and handle page-specific interactions such as authentication, cart updates, notifications, and analytics.

4. **API boundary and domain routing**
   - Routes are split by business area: `auth`, `users`, `chefs`, `dishes`, `orders`, `cart`, `favorites`, `reviews`, `notifications`, `statistics`, and `admin`.
   - This boundary maps cleanly to the main use-case groups in the README: customer browsing/orders, chef management, and admin moderation.
   - `backend/controllers/*Controller.js` files form the request-handling layer for each domain.

5. **Core business domains**
   - **Users** and **Chefs** are intentionally separate account tables, not inheritance-based variants of one table.
   - Other core domains are `Dish`, `Order`, `OrderItem`, `Review`, `Favorite`, `Notification`, and `PasswordReset`.
   - This separation supports distinct lifecycle rules for customers, chefs, and admins, and keeps chef onboarding/moderation independent from customer identity.

6. **Order and menu flow**
   - Customer-facing flows start with browsing chefs/dishes, then move into **cart**, **checkout**, and **order creation**.
   - Orders are decomposed into `Order` plus `OrderItem` records, which is the main persistence boundary for multi-item purchases.
   - Chefs manage order state transitions such as accept/reject/complete, while customers can track and cancel orders depending on status.

7. **Chef operations and availability**
   - Chef capabilities include profile management, dish CRUD, image upload, and sales/statistics views.
   - `ChefAvailability` indicates a separate scheduling layer for availability slots, holidays/leaves, and automatic rejection outside working hours.
   - This means order acceptance is constrained not just by status, but also by chef availability rules.

8. **Favorites, reviews, and discovery**
   - `Favorite` supports user-curated saved items, likely spanning dishes and/or chefs as described in the README.
   - `Review` captures ratings and feedback for chefs, feeding both dish/chef discovery and reputation.
   - `dishes`, `chefs`, and `reviews` routes together implement browsing, filtering, and trust-building for the marketplace side of the system.

9. **Authentication and authorization**
   - `backend/middleware/auth.js` enforces protected access and role-based boundaries for **User / Chef / Admin**.
   - Authentication includes **JWT access/refresh tokens**, **Google OAuth2** login, bcrypt password hashing, and role-aware route protection.
   - Account state logic is centralized in `backend/utils/accountStatus.js`, which likely supports moderation actions such as activation/deactivation.

10. **Password recovery and email**
   - OTP-based password reset is modeled explicitly through `PasswordReset`, separate from user credentials.
   - `backend/utils/mailer.js` and `backend/controllers/authController.js` coordinate email delivery and token validation.
   - The README’s 15-minute hashed OTP policy suggests the reset flow is designed as a short-lived, server-verified security path.

11. **Notifications and real-time delivery**
   - Notifications are both persisted (`Notification` model) and pushed in real time through `backend/socket/notificationSocket.js`.
   - `backend/services/notificationService.js` appears to centralize notification creation and fan-out, so events from orders or admin actions can become both database records and socket events.
   - This is one of the few genuinely asynchronous boundaries in the system.

12. **Admin and analytics**
   - `admin` routes and `statisticsController.js` back the admin dashboard and platform reporting.
   - Admin capabilities include moderating users/chefs, viewing system metrics, and monitoring overall platform activity.
   - Chef-specific statistics are also supported, meaning analytics is split between **platform-wide** and **per-chef** views.

13. **Infrastructure and storage**
   - The data layer is **MySQL via Sequelize**.
   - Image handling is implied by dish/profile uploads and the presence of view scripts for upload-heavy pages; uploaded assets are part of the backend-managed filesystem rather than an external media service.
   - Email uses **Nodemailer with Gmail App Passwords**, and external auth depends on **Google OAuth2**.

14. **What to show in an architecture diagram**
   - A useful diagram would show: **browser views/scripts → Express routes → controllers → services → Sequelize models → MySQL**, with side channels for **email OTP**, **Google OAuth**, and **socket-based notifications**.
   - The key boundaries are role-based access, separate user/chef identities, and the split between synchronous request handling and real-time notification delivery.

Main entry points: [`backend/server.js`](https://github.com/yasen-ab/homeychefpt/blob/main/backend/server.js) (Server), [`backend/views/index.html`](https://github.com/yasen-ab/homeychefpt/blob/main/backend/views/index.html) (Browser UI), [`backend/middleware/auth.js`](https://github.com/yasen-ab/homeychefpt/blob/main/backend/middleware/auth.js) (Auth Guard), [`backend/models/User.js`](https://github.com/yasen-ab/homeychefpt/blob/main/backend/models/User.js) (Core Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_views["Browser UI<br/>served views<br/>[index.html]"]
end

subgraph group_api["API Layer"]
  node_server["Server<br/>Express entrypoint<br/>[server.js]"]
  node_authmw["Auth Guard<br/>middleware<br/>[auth.js]"]
  node_authroutes["Auth Routes<br/>route module<br/>[auth.js]"]
  node_userroutes["User Routes<br/>route module<br/>[users.js]"]
  node_chefroutes["Chef Routes<br/>route module<br/>[chef.js]"]
  node_dishroutes["Dish Routes<br/>route module<br/>[dishes.js]"]
  node_orderroutes["Order Routes<br/>route module<br/>[orders.js]"]
  node_adminroutes["Admin Routes<br/>route module<br/>[admin.js]"]
  node_notifroutes["Notify Routes<br/>route module<br/>[notifications.js]"]
end

subgraph group_domain["Domain Logic"]
  node_authctl["Auth Controller<br/>[authController.js]"]
  node_orderctl["Order Controller<br/>[orderController.js]"]
  node_chefctl["Chef Controller<br/>[chefController.js]"]
  node_statsctl["Stats Controller"]
  node_notifsvc["Notification Service"]
end

subgraph group_data["Data & Infra"]
  node_dbconfig["DB Config<br/>Sequelize config<br/>[database.js]"]
  node_dbsync["Sync DB<br/>bootstrap helper<br/>[syncDatabase.js]"]
  node_notificationsocket(("Socket Channel<br/>realtime socket"))
  node_mailer["Mailer<br/>email utility<br/>[mailer.js]"]
  node_models[("Core Models<br/>Sequelize models<br/>[User.js]")]
end

node_server -->|"configures"| node_dbconfig
node_server -->|"syncs"| node_dbsync
node_server -->|"mounts"| node_authroutes
node_server -->|"mounts"| node_userroutes
node_server -->|"mounts"| node_chefroutes
node_server -->|"mounts"| node_dishroutes
node_server -->|"mounts"| node_orderroutes
node_server -->|"mounts"| node_adminroutes
node_server -->|"mounts"| node_notifroutes
node_server -->|"serves"| node_views
node_authroutes -->|"protects"| node_authmw
node_authroutes -->|"dispatches"| node_authctl
node_userroutes -->|"protects"| node_authmw
node_chefroutes -->|"protects"| node_authmw
node_dishroutes -->|"protects"| node_authmw
node_orderroutes -->|"protects"| node_authmw
node_adminroutes -->|"protects"| node_authmw
node_notifroutes -->|"protects"| node_authmw
node_authctl -->|"uses"| node_models
node_authctl -->|"emails"| node_mailer
node_authctl -.->|"signs in"| node_notificationsocket
node_chefctl -->|"uses"| node_models
node_orderctl -->|"uses"| node_models
node_orderctl -->|"announces"| node_notifsvc
node_statsctl -->|"reads"| node_models
node_notifsvc -->|"persists"| node_models
node_notifsvc -->|"pushes"| node_notificationsocket
node_views -->|"calls"| node_authroutes
node_views -->|"calls"| node_orderroutes
node_views -->|"calls"| node_chefroutes
node_views -->|"calls"| node_dishroutes
node_views -->|"calls"| node_adminroutes
node_views -->|"calls"| node_notifroutes
node_views -->|"subscribes"| node_notificationsocket

click node_server "https://github.com/yasen-ab/homeychefpt/blob/main/backend/server.js"
click node_dbconfig "https://github.com/yasen-ab/homeychefpt/blob/main/backend/config/database.js"
click node_dbsync "https://github.com/yasen-ab/homeychefpt/blob/main/backend/config/syncDatabase.js"
click node_authmw "https://github.com/yasen-ab/homeychefpt/blob/main/backend/middleware/auth.js"
click node_authroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/auth.js"
click node_userroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/users.js"
click node_chefroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/chef.js"
click node_dishroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/dishes.js"
click node_orderroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/orders.js"
click node_adminroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/admin.js"
click node_notifroutes "https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/notifications.js"
click node_authctl "https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/authController.js"
click node_orderctl "https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/orderController.js"
click node_chefctl "https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/chefController.js"
click node_statsctl "https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/statisticsController.js"
click node_notifsvc "https://github.com/yasen-ab/homeychefpt/blob/main/backend/services/notificationService.js"
click node_notificationsocket "https://github.com/yasen-ab/homeychefpt/blob/main/backend/socket/notificationSocket.js"
click node_mailer "https://github.com/yasen-ab/homeychefpt/blob/main/backend/utils/mailer.js"
click node_models "https://github.com/yasen-ab/homeychefpt/blob/main/backend/models/User.js"
click node_views "https://github.com/yasen-ab/homeychefpt/blob/main/backend/views/index.html"

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_views toneBlue
class node_server,node_authmw,node_authroutes,node_userroutes,node_chefroutes,node_dishroutes,node_orderroutes,node_adminroutes,node_notifroutes toneAmber
class node_authctl,node_orderctl,node_chefctl,node_statsctl,node_notifsvc toneMint
class node_dbconfig,node_dbsync,node_notificationsocket,node_mailer,node_models toneRose
```

## Components

### Presentation

Browser-served HTML/CSS/JS UI

- [Browser UI](https://github.com/yasen-ab/homeychefpt/blob/main/backend/views/index.html): served views · Server-rendered pages and page scripts for customers, chefs, and admins. · `backend/views/index.html`

### API Layer

Express entrypoints, routes, and middleware

- [Server](https://github.com/yasen-ab/homeychefpt/blob/main/backend/server.js): Express entrypoint · Bootstraps the app and wires routes, views, and infrastructure. · `backend/server.js`
- [Auth Guard](https://github.com/yasen-ab/homeychefpt/blob/main/backend/middleware/auth.js): middleware · Protects routes and enforces role-based access. · `backend/middleware/auth.js`
- [Auth Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/auth.js): route module · Login, registration, OAuth, and password recovery endpoints. · `backend/routes/auth.js`
- [User Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/users.js): route module · User account and profile endpoints. · `backend/routes/users.js`
- [Chef Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/chef.js): route module · Chef profile, availability, and management endpoints. · `backend/routes/chef.js`
- [Dish Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/dishes.js): route module · Menu and dish browsing or CRUD endpoints. · `backend/routes/dishes.js`
- [Order Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/orders.js): route module · Cart checkout and order lifecycle endpoints. · `backend/routes/orders.js`
- [Admin Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/admin.js): route module · Moderation and admin dashboard endpoints. · `backend/routes/admin.js`
- [Notify Routes](https://github.com/yasen-ab/homeychefpt/blob/main/backend/routes/notifications.js): route module · Notification retrieval and management endpoints. · `backend/routes/notifications.js`

### Domain Logic

Controllers, services, and business rules

- [Auth Controller](https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/authController.js): controller · Handles authentication, OTP reset, Google login, and account state flow. · `backend/controllers/authController.js`
- [Order Controller](https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/orderController.js): controller · Coordinates cart checkout and order state transitions. · `backend/controllers/orderController.js`
- [Chef Controller](https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/chefController.js): controller · Manages chef profiles, availability, and chef-facing actions. · `backend/controllers/chefController.js`
- [Stats Controller](https://github.com/yasen-ab/homeychefpt/blob/main/backend/controllers/statisticsController.js): controller · Serves platform and chef statistics. · `backend/controllers/statisticsController.js`
- [Notification Service](https://github.com/yasen-ab/homeychefpt/blob/main/backend/services/notificationService.js): service · Creates notifications and fans them out to real-time clients. · `backend/services/notificationService.js`

### Data & Infra

Persistence, sockets, and external integrations

- [DB Config](https://github.com/yasen-ab/homeychefpt/blob/main/backend/config/database.js): Sequelize config · Configures the MySQL connection and schema sync support. · `backend/config/database.js`
- [Sync DB](https://github.com/yasen-ab/homeychefpt/blob/main/backend/config/syncDatabase.js): bootstrap helper · Initializes or synchronizes database schema. · `backend/config/syncDatabase.js`
- [Socket Channel](https://github.com/yasen-ab/homeychefpt/blob/main/backend/socket/notificationSocket.js): realtime socket · Pushes notification events to connected clients. · `backend/socket/notificationSocket.js`
- [Mailer](https://github.com/yasen-ab/homeychefpt/blob/main/backend/utils/mailer.js): email utility · Sends OTP and account-related emails. · `backend/utils/mailer.js`
- [Core Models](https://github.com/yasen-ab/homeychefpt/blob/main/backend/models/User.js): Sequelize models · Users, chefs, dishes, orders, reviews, favorites, notifications, and reset tokens. · `backend/models/User.js`

## Connections

- Server → DB Config: configures · Initializes the database connection before handling requests.
- Server → Sync DB: syncs · Can prepare or synchronize schema at startup.
- Server → Auth Routes: mounts · Registers domain route modules on the Express app.
- Server → User Routes: mounts · Registers domain route modules on the Express app.
- Server → Chef Routes: mounts · Registers domain route modules on the Express app.
- Server → Dish Routes: mounts · Registers domain route modules on the Express app.
- Server → Order Routes: mounts · Registers domain route modules on the Express app.
- Server → Admin Routes: mounts · Registers domain route modules on the Express app.
- Server → Notify Routes: mounts · Registers domain route modules on the Express app.
- Server → Browser UI: serves · Hosts the browser UI from backend/views.
- Auth Routes → Auth Guard: protects · Applies route protection where needed.
- Auth Routes → Auth Controller: dispatches · Forwards requests into authentication handling.
- User Routes → Auth Guard: protects · Enforces role-based access.
- Chef Routes → Auth Guard: protects · Enforces role-based access.
- Dish Routes → Auth Guard: protects · Enforces role-based access for mutating actions.
- Order Routes → Auth Guard: protects · Enforces authenticated order and cart access.
- Admin Routes → Auth Guard: protects · Restricts moderation and reporting endpoints.
- Notify Routes → Auth Guard: protects · Restricts notification access.
- Auth Controller → Core Models: uses · Reads and updates user, chef, and password reset records.
- Auth Controller → Mailer: emails · Sends OTP and recovery messages.
- Auth Controller → Socket Channel: signs in · May emit account-related socket events through shared app state.
- Chef Controller → Core Models: uses · Manages chef profile and availability records.
- Order Controller → Core Models: uses · Persists orders, items, and status changes.
- Order Controller → Notification Service: announces · Triggers notifications for order events.
- Stats Controller → Core Models: reads · Aggregates platform and chef metrics from persisted data.
- Notification Service → Core Models: persists · Creates notification records before delivery.
- Notification Service → Socket Channel: pushes · Fans notification events out to connected clients.
- Browser UI → Auth Routes: calls · Login, register, and reset flows use auth endpoints.
- Browser UI → Order Routes: calls · Cart, checkout, and order pages use order endpoints.
- Browser UI → Chef Routes: calls · Chef dashboard and profile pages use chef endpoints.
- Browser UI → Dish Routes: calls · Menu and browse pages use dish endpoints.
- Browser UI → Admin Routes: calls · Admin dashboards use moderation endpoints.
- Browser UI → Notify Routes: calls · Notification pages poll or fetch notification data.
- Browser UI → Socket Channel: subscribes · Client scripts listen for real-time notification updates.
