# makanmatch/backend architecture

> Architecture diagram of the GitHub repository makanmatch/backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/makanmatch/backend
- Repository: https://github.com/makanmatch/backend

## Overview

##### Project type and purpose
- From the file tree and README, MakanMatch Backend is a Node.js/Express full-stack application’s server component.
- Purpose: Provide a REST + WebSocket API for a community food-sharing platform, handling user identity, listings, reservations, reviews, real-time chat, analytics, file storage and admin operations.

##### File structure
- Top-level directories:
- config: static configs
- middleware: request lifecycle handlers (auth, analytics, file filters, logging, response processors)
- models: Sequelize ORM definitions for MySQL/SQLite (User, Host, Listing, Reservation, Review, Analytics, etc.)
- routes: Express route modules grouped by domain (cdn, chat, chatbot, identity, listings, orders, reviews, misc) and a WebSocketServer for chat
- services: business-logic layer (Analytics, TokenManager, FileManager, Logger, Emailer, OpenAIChat, Cache, etc.)
- public & views: static assets & email templates
- index.js: Express app entry point
- Auxiliary files: dbTools.js (database helpers), superuserScript.py, ConfiguringSystem.md

##### Extract architectural insights from the README
- Tech stack: Node.js, Express.js, Sequelize ORM, AWS RDS (MySQL), Firebase Cloud Storage, Google Cloud (Maps SDK & Geocoding), Google SMTP, OpenAI API
- Major features: JWT auth, layered middleware, service layer abstraction, real-time WebSocket chat, analytics aggregation, email templating

a. Main components
- Clients (Web SPA / mobile): HTTP(S) & WebSocket connections
- API Gateway (Express app)
- Middleware chain (auth, headersCheck, analytics, logging, file filters, response processors)
- Route handlers/controllers (routes/* modules)
- Service layer (services/*)
- Data layer (models/* via Sequelize)
- Primary database (AWS RDS MySQL, dev SQLite)
- File storage (Firebase Cloud Storage + local fallback)
- WebSocket server (for chat)
- External services: Google Maps API, Google SMTP, OpenAI GPT API
- Admin tools (superuserScript.py + admin route modules)
b. Relationships & data flows
1. Client → Express API entry (index.js)
2. Request passes through ordered middleware (auth → analytics → headersCheck → etc.)
3. Middleware may invoke TokenManager, Analytics, Logger, FileManager
4. Route handler calls service layer
5. Service layer interacts with Sequelize models (reads/writes DB) and external APIs (Firebase, SMTP, Maps, OpenAI)
6. WebSocketServer manages real-time chat channel parallel to REST flows
7. Responses go back through responseProcessors before reaching client
c. Architectural patterns & principles
- Layered architecture (Controller → Service → Data)
- MVC-style separation
- Middleware pipeline for cross-cutting concerns
- Dependency injection via services/index.js
- External adapter pattern for third-party integrations (FileManager, OpenAIChat, Emailer)
d. Key technologies & libraries
- Express.js (web framework)
- Sequelize ORM (database access)
- JWT & TokenManager (authentication)
- Firebase SDK (storage)
- AWS RDS (MySQL)
- Google Maps & SMTP APIs
- OpenAI GPT API integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Web / Mobile Clients"]:::external
    Clients -->|"HTTP(S), WebSocket"| APIGateway

    %% API Gateway
    APIGateway["API Gateway\n(index.js)"]:::entry
    click APIGateway "https://github.com/makanmatch/backend/blob/main/index.js"

    %% Middleware Chain
    subgraph "Middleware Pipeline"
        direction TB
        Auth["Authentication\n(middleware/auth.js)"]:::middleware
        AnalyticsMW["Analytics Tracking\n(middleware/analytics.js)"]:::middleware
        Headers["Header Checks\n(middleware/headersCheck.js)"]:::middleware
        LoggingMW["Logging\n(middleware/logRoutes.js)"]:::middleware
        FileFilter["Image File Filter\n(middleware/imageFileFilter.js)"]:::middleware
        StoreFile["Store File Variants\n(middleware/storeFile.js\nstoreFiles.js\nstoreImage.js\nstoreImages.js)"]:::middleware
        ResponseProc["Response Processors\n(middleware/responseProcessors/index.js)"]:::middleware
    end
    APIGateway --> Auth --> AnalyticsMW --> Headers --> LoggingMW --> FileFilter --> StoreFile --> ResponseProc

    %% Routes / Controllers
    subgraph "Route Handlers"
        direction TB
        Identity["Identity & User\n(routes/identity/)"]:::route
        AdminAPI["Admin APIs\n(routes/identity/Admin/)"]:::route
        Listings["Listings & Analytics\n(routes/listings/)"]:::route
        Orders["Orders & Reservations\n(routes/orders/)"]:::route
        Reviews["Reviews\n(routes/reviews/)"]:::route
        CDN["CDN / Static\n(routes/cdn/)"]:::route
        ChatREST["Chat Controller\n(routes/chat/manageChat.js)"]:::route
        WebSocketSrv["WebSocket Server\n(routes/chat/WebSocketServer.js)"]:::entry
        Chatbot["Chatbot\n(routes/chatbot/MakanBot.js)"]:::route
        Misc["Miscellaneous\n(routes/misc.js\nroutes/index.js)"]:::route
    end
    ResponseProc --> Identity
    ResponseProc --> AdminAPI
    ResponseProc --> Listings
    ResponseProc --> Orders
    ResponseProc --> Reviews
    ResponseProc --> CDN
    ResponseProc --> ChatREST
    ResponseProc --> Chatbot
    ResponseProc --> Misc
    APIGateway --> WebSocketSrv

    click Identity "https://github.com/makanmatch/backend/tree/main/routes/identity/"
    click AdminAPI "https://github.com/makanmatch/backend/tree/main/routes/identity/Admin/"
    click Listings "https://github.com/makanmatch/backend/tree/main/routes/listings/"
    click Orders "https://github.com/makanmatch/backend/tree/main/routes/orders/"
    click Reviews "https://github.com/makanmatch/backend/tree/main/routes/reviews/"
    click CDN "https://github.com/makanmatch/backend/tree/main/routes/cdn/"
    click ChatREST "https://github.com/makanmatch/backend/blob/main/routes/chat/manageChat.js"
    click WebSocketSrv "https://github.com/makanmatch/backend/blob/main/routes/chat/WebSocketServer.js"
    click Chatbot "https://github.com/makanmatch/backend/blob/main/routes/chatbot/MakanBot.js"
    click Misc "https://github.com/makanmatch/backend/blob/main/routes/misc.js"

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AnalyticsSvc["Analytics & BootCheck\n(services/Analytics.js\nservices/BootCheck.js)"]:::service
        AuthSvc["Token & Encryption\n(services/TokenManager.js\nservices/Encryption.js)"]:::service
        FileSvc["File Management\n(services/FileManager.js\nservices/FileOps.js\nservices/FireStorage.js)"]:::service
        CacheExt["Cache & Extensions\n(services/Cache.js\nservices/Extensions.js\nservices/Universal.js)"]:::service
        Comm["Communication\n(services/Emailer.js\nservices/HTMLRenderer.js)"]:::service
        LoggerSvc["Logging Service\n(services/Logger.js)"]:::service
        OpenAI["OpenAI Integration\n(services/OpenAIChat.js)"]:::service
        ServiceIndex["DI Container\n(services/index.js)"]:::service
    end
    Identity --> ServiceIndex
    AdminAPI --> ServiceIndex
    Listings --> ServiceIndex
    Orders --> ServiceIndex
    Reviews --> ServiceIndex
    CDN --> ServiceIndex
    ChatREST --> ServiceIndex
    WebSocketSrv --> ServiceIndex
    Chatbot --> ServiceIndex
    Misc --> ServiceIndex

    click AnalyticsSvc "https://github.com/makanmatch/backend/blob/main/services/Analytics.js"
    click AuthSvc "https://github.com/makanmatch/backend/blob/main/services/TokenManager.js"
    click FileSvc "https://github.com/makanmatch/backend/blob/main/services/FileManager.js"
    click CacheExt "https://github.com/makanmatch/backend/blob/main/services/Cache.js"
    click Comm "https://github.com/makanmatch/backend/blob/main/services/Emailer.js"
    click LoggerSvc "https://github.com/makanmatch/backend/blob/main/services/Logger.js"
    click OpenAI "https://github.com/makanmatch/backend/blob/main/services/OpenAIChat.js"
    click ServiceIndex "https://github.com/makanmatch/backend/blob/main/services/index.js"

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Models["Sequelize Models\n(models/*.js)"]:::data
        ORMInit["ORM Init\n(models/index.js)"]:::data
        DB["MySQL / SQLite\n(AWS RDS)"]:::database
    end
    ServiceIndex --> Models --> ORMInit --> DB

    click Models "https://github.com/makanmatch/backend/tree/main/models/"
    click ORMInit "https://github.com/makanmatch/backend/blob/main/models/index.js"

    %% File Storage
    FileSvc -->|"Uploads"| FirebaseFS
    subgraph "File Storage"
        FirebaseFS["Firebase Cloud Storage\n(or local fallback)"]:::database
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        GoogleMaps["Google Maps API"]:::external
        GoogleSMTP["Google SMTP"]:::external
        OpenAIApi["OpenAI GPT API"]:::external
    end
    ServiceIndex --> GoogleMaps
    Comm --> GoogleSMTP
    OpenAI --> OpenAIApi

    %% Admin Tools
    SuperUser["Superuser Script\n(superuserScript.py)"]:::entry
    SuperUser --> DB
    click SuperUser "https://github.com/makanmatch/backend/blob/main/superuserScript.py"

    %% Static Assets & Views
    Public["Public Assets\n(public/logos/)"]:::database
    Views["Email & Web Templates\n(views/)"]:::database
    click Public "https://github.com/makanmatch/backend/tree/main/public/logos/"
    click Views "https://github.com/makanmatch/backend/tree/main/views/"

    %% Config & Helpers
    Config["Configuration\n(config/boilerplateConfig.json)"]:::config
    DBTools["DB Helpers\n(dbTools.js)"]:::config
    click Config "https://github.com/makanmatch/backend/blob/main/config/boilerplateConfig.json"
    click DBTools "https://github.com/makanmatch/backend/blob/main/dbTools.js"

    APIGateway --> Config
    ServiceIndex --> DBTools

    %% Styles
    classDef entry fill:#B3CDE3,stroke:#036; color:#000
    classDef middleware fill:#DDDDDD,stroke:#AAA; color:#000
    classDef route fill:#A6CEE3,stroke:#036; color:#000
    classDef service fill:#B2DF8A,stroke:#060; color:#000
    classDef data fill:#FDB462,stroke:#A60; color:#000
    classDef database fill:#FB9A99,stroke:#A00; color:#000
    classDef external fill:#CAB2D6,stroke:#606; color:#000
    classDef config fill:#FFFFB3,stroke:#CC0; color:#000
```
