# matthew-ngzc/smunch architecture

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

- Interactive diagram: https://gitdiagram.com/matthew-ngzc/smunch
- Repository: https://github.com/matthew-ngzc/smunch

## Overview

##### Project Type and Purpose
- This is a full-stack web application (SMUNCH) for campus group food ordering.
- Frontend: Vue.js SPA with real-time features, hosted on Vercel/Firebase.
- Backend: Express.js REST API with MVC structure, cron jobs, Telegram bot integration, uses MySQL (primary), Redis (caching), Supabase (realtime), Firestore (logging), and external APIs (Weather/Bus, Payment gateway, OpenAI).

##### File Structure Highlights
- Top-level:
- Backend/ – Node.js project (`src/` contains controllers, routes, services, models, utils, middlewares, cron, lib).
- Backend/src/telegram_bot – Python Telegram bot component.
- Frontend/ – Vue.js project (`src/` contains components, views, router, stores, services, lib).
- Frontend/tests – Unit & E2E tests.
- Configuration/deploy files: `.github/workflows`, `vercel.json`, `firebase.json`.

##### README Insights
- Core features: Class-based grouping, order management, payment, runner matching, real-time tracking, auto-cancellation.
- Tech stack: Vue.js, Express.js, MySQL, Bootstrap, Tailwind CSS, OpenAI API, Weather/Bus API.

##### Main Components
a. User Interface (Browser or Mobile App)
b. Frontend SPA (Vue.js + Router + State Stores + Supabase Real-Time)
c. Backend API (Express.js)
- Controllers (admin, auth, order, payment, telegram, weather, etc.)
- Services & Utilities
- Middlewares (auth, rate-limit, error, role)
- Cron Scheduler (emails.cron.js, scheduler.js)
- Telegram Bot Controller & Separate Python Bot
d. Databases & Caches
- MySQL (Primary relational data)
- Redis (Session/caching)
- Supabase (Real-time pub/sub)
- Firestore (Audit logs, analytics)
e. External Services
- Payment Gateway API (e.g., Stripe)
- OpenAI API
- Weather/Bus API
- Email Service (SMTP via Mailer util)
- Telegram API
f. Deployment/Hosting
- Vercel/Firebase Hosting (Frontend)
- Heroku/AWS/DigitalOcean (Backend)
- GitHub Actions CI/CD

##### Relationships & Data Flows
- User → Frontend (HTTP/REST over HTTPS)
- Fetch UI, assets, real-time socket connections.
- Frontend ↔ Backend API
- CRUD orders, auth, merchant/menu data, WebSocket or Supabase real-time channels.
- Backend → Databases/Caches
- Read/write MySQL, cache queries in Redis, push events to Supabase for real-time updates, write logs to Firestore.
- Backend → External APIs
- Payment processing, weather data, bus info, AI prompts.
- Cron Jobs → Backend Services → Database / Email
- Backend ↔ Python Telegram Bot
- Controller triggers notifications; Python bot polls RabbitMQ or webhook to send messages.

##### Architectural Patterns & Principles
- MVC on backend, separating controllers/services/models.
- Single-Page Application on frontend, state management via Pinia/Vuex style stores.
- Event-driven real-time updates using Supabase or WebSockets.
- Layered security with JWT auth, role-based middleware, rate limiting.
- Micro-component approach: separate Python bot service.
- Scheduled tasks via cron module.

- Notes for deployment (e.g., hosting targets, CI/CD).

## Diagram (Mermaid)

```mermaid
graph TB
    %% User
    Browser["Browser / Mobile"]:::user
    click Browser "https://github.com/matthew-ngzc/smunch/tree/main/Frontend/src/"

    %% Frontend Layer
    subgraph "Frontend SPA" 
        FE_Router["Router"]:::frontend
        FE_Stores["State Stores"]:::frontend
        FE_API["axiosInstance"]:::frontend
        FE_Socket["Supabase WS"]:::frontend
    end
    FrontendSPA["Frontend SPA"]:::frontend
    click FrontendSPA "https://github.com/matthew-ngzc/smunch/tree/main/Frontend/src/"
    click FE_Router "https://github.com/matthew-ngzc/smunch/blob/main/Frontend/src/router/index.js"
    click FE_Stores "https://github.com/matthew-ngzc/smunch/tree/main/Frontend/src/stores/"
    click FE_Socket "https://github.com/matthew-ngzc/smunch/blob/main/Frontend/src/lib/supabaseClient.js"

    Browser -->|"HTTP/REST"| FrontendSPA
    FrontendSPA -->|"HTTP/REST"| API

    %% Backend API
    API["Express API\n(Index.js)"]:::backend
    click API "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/index.js"

    subgraph "API Controllers" 
        AuthCtrl["Auth Controller"]:::backend
        OrderCtrl["Order Controller"]:::backend
        PaymentCtrl["Payment Controller"]:::backend
        TelegramCtrl["Telegram Controller"]:::backend
        WeatherCtrl["Weather Controller"]:::backend
        AdminCtrls["Admin/Contact/Merchant/User Controllers"]:::backend
    end
    click AuthCtrl "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/controllers/auth.controller.js"
    click OrderCtrl "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/controllers/order.controller.js"
    click PaymentCtrl "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/controllers/payment.controller.js"
    click TelegramCtrl "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/controllers/telegram.controller.js"
    click WeatherCtrl "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/controllers/weather.controller.js"
    click AdminCtrls "https://github.com/matthew-ngzc/smunch/tree/main/Backend/src/controllers/"

    API --> AuthCtrl
    API --> OrderCtrl
    API --> PaymentCtrl
    API --> TelegramCtrl
    API --> WeatherCtrl
    API --> AdminCtrls

    subgraph "API Routes"
        Routes["API Routes"]:::backend
    end
    click Routes "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/routes/*.routes.js"
    API --> Routes
    Routes --> AuthCtrl
    Routes --> OrderCtrl
    Routes --> PaymentCtrl
    Routes --> TelegramCtrl
    Routes --> WeatherCtrl

    subgraph "Services Layer"
        PaymentSvc["Payment Service"]:::backend
        OtherSvc["Other Services"]:::backend
    end
    click PaymentSvc "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/services/payment.service.js"
    API --> PaymentSvc
    AuthCtrl --> OtherSvc

    subgraph "Middlewares"
        AuthMW["Authentication"]:::backend
        RateMW["Rate Limiting"]:::backend
        RoleMW["Role-Based Access"]:::backend
        ErrorMW["Error Handling"]:::backend
    end
    click AuthMW "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/middlewares/auth.middleware.js"
    click RateMW "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/middlewares/rateLimit.middleware.js"
    click RoleMW "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/middlewares/role.middleware.js"
    click ErrorMW "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/middlewares/error.middleware.js"

    API --> AuthMW
    API --> RateMW
    API --> RoleMW
    API --> ErrorMW

    %% Cron & Scheduler
    subgraph "Cron Jobs & Scheduler"
        Scheduler["Scheduler Setup"]:::aux
        EmailCron["Email Cron Jobs"]:::aux
    end
    click Scheduler "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/cron/scheduler.js"
    click EmailCron "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/cron/emails.cron.js"
    Scheduler --> EmailCron
    Scheduler --> OtherSvc

    %% Python Telegram Bot
    subgraph "Python Telegram Bot"
        TeleBot["tele_bot.py"]:::aux
    end
    click TeleBot "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/telegram_bot/tele_bot.py"
    TelegramCtrl -->|"AMQP/Webhook"| TeleBot

    %% Databases & Caches
    subgraph "Databases & Caches"
        MySQL[(MySQL)]:::db
        Redis[(Redis Cache)]:::db
        SupaDB[(Supabase Realtime)]:::db
        Firestore[(Firestore Logs)]:::db
    end
    API -->|"SQL"| MySQL
    API -->|"Cache"| Redis
    API -->|"Pub/Sub"| SupaDB
    API -->|"Write"| Firestore

    %% External Services
    subgraph "External Services"
        PaymentAPI["Payment Gateway"]:::ext
        WeatherAPI["Weather/Bus API"]:::ext
        OpenAIAPI["OpenAI API"]:::ext
        EmailSvc["Email Service"]:::ext
        TelegramAPI["Telegram API"]:::ext
    end
    API -->|"HTTPS"| PaymentAPI
    API -->|"HTTPS"| WeatherAPI
    API -->|"HTTPS"| OpenAIAPI
    API -->|"SMTP"| EmailSvc
    TeleBot -->|"HTTPS"| TelegramAPI

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        CI["GitHub Actions CI/CD"]:::infra
        FrontendHost["Vercel / Firebase Hosting"]:::infra
        BackendHost["Heroku / AWS / DigitalOcean"]:::infra
        Swagger["Swagger Config"]:::backend
    end
    click CI "https://github.com/matthew-ngzc/smunch/blob/main/github/workflows/deploy.yml"
    click FrontendHost "https://github.com/matthew-ngzc/smunch/blob/main/Frontend/vercel.json"
    click FrontendHost "https://github.com/matthew-ngzc/smunch/blob/main/Frontend/firebase.json"
    click Swagger "https://github.com/matthew-ngzc/smunch/blob/main/Backend/src/config/swagger.config.js"
    CI --> FrontendHost
    CI --> BackendHost
    API --> Swagger

    %% Legend
    subgraph "Legend"
        U["User-Facing"]:::user
        B["Backend"]:::backend
        D["Databases/Caches"]:::db
        E["External Services"]:::ext
        A["Auxiliary"]:::aux
        I["Infrastructure/CI/CD"]:::infra
        F["Frontend"]:::frontend
    end

    classDef user fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:1px;
    classDef db fill:#fff3cd,stroke:#856404,stroke-width:1px;
    classDef ext fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
    classDef aux fill:#f8f9fa,stroke:#6c757d,stroke-width:1px;
    classDef infra fill:#d1ecf1,stroke:#0c5460,stroke-width:1px;
```
