How aayushsinghal294/bingo works
Project Type and Purpose
• This is a full-stack web application with three main tiers:
• Frontend client (React/Vite)
• Backend API (Node.js/Express + MongoDB)
• AI microservice (Python/Flask)
• Purpose: Provide gamified, AI-verified waste disposal proof, dustbin mapping, leaderboards, and rewards.
File Structure
• Top-level directories:
• client – React app (src/components, pages, services, utils)
• server – Node/Express API (controllers, routes, models, seed scripts)
• ai_backend – Flask microservice for face & activity verification
• Config and deployment:
• Procfile in ai_backend and server for Heroku or similar
• requirements.txt and package.json files for dependency management
• Static assets:
• yolov8n.pt model in ai_backend
README Insights
• Three-tier architecture described under “Tech Stack.”
• Integration points:
• Frontend → Express API
• Express API ↔ Flask AI service (via REST with API key, CORS)
• Express API ↔ MongoDB Atlas (via Mongoose)
• Express API ↔ Cloudinary (media storage)
• Authentication via Clerk in frontend and Express middleware
Main Components
a. Frontend:
• Browser (React app)
• React Router, Redux Toolkit, Leaflet
• HTML5 camera/file input → CropperJS
b. Backend API:
• Node.js + Express server
• Controllers: chat, dailyQuest, image, leaderboard, missions, rewards
• Mongoose models and MongoDB Atlas
• Seed scripts for question bank
c. AI Microservice:
• Python Flask service
• DeepFace, OpenCV/TensorFlow, image hashing
• yolov8n object detection model
d. External Services:
• MongoDB Atlas (database)
• Cloudinary (image storage)
• Clerk (authentication)
• OpenStreetMap API (maps)
e. Clients & Channels:
• Mobile/desktop browser
• HTTP/HTTPS REST calls
• CORS and API key security between Node and Flask
Relationships and Data Flows
• User interacts with React UI → REST call to Express API
• Express API routes request:
• User endpoints (register/login) via Clerk
• Proof upload → Express stores image temporarily in Cloudinary → forwards URL + metadata to Flask AI
• Flask returns verified/unverified → Express updates MongoDB and triggers reward logic
• Leaderboard and map data fetched from MongoDB → returned to React
• Dustbin map requests → Express queries geo-tagged Dustbin collection → React/Leaflet renders markers
Architectural Patterns & Design Principles
• Three-tier separation (Presentation, Business Logic, Data)
• Microservice for AI concerns to isolate ML dependencies
• RESTful APIs with clear resource‐based routes
• Use of cloud services for scalability (MongoDB Atlas, Cloudinary)
• MVC-style organization in both backend (controllers, models, routes) and frontend (components, pages, services)
Elements
• Frontend (blue)
• Backend (green)
• Microservice (orange)
• External services (gray)
• Authentication flow separately (Clerk → JWT/session tokens in Express)