How matthew-ngzc/smunch works
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).