# aayushsinghal294/bingo architecture

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

- Interactive diagram: https://gitdiagram.com/aayushsinghal294/bingo
- Repository: https://github.com/aayushsinghal294/bingo

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser)" 
        direction TB
        B["Browser / React Client"]:::frontend
        subgraph "React Application"
            direction TB
            main["main.jsx"]:::frontend
            comp["Components"]:::frontend
            pages["Pages"]:::frontend
            services["Services"]:::frontend
            utils["Utils"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend API (Express)" 
        direction TB
        API["Express API"]:::backend
        serverjs["server.js"]:::backend
        controllers["Controllers"]:::backend
        routes["Routes"]:::backend
        models["Models"]:::backend
        scripts["Seed Script"]:::backend
        procBackend["Procfile"]:::backend
        pkg["package.json"]:::backend
    end

    %% AI Microservice Layer
    subgraph "AI Microservice (Flask)"
        direction TB
        AI["Flask Service"]:::microservice
        aiApp["app.py"]:::microservice
        aiReq["requirements.txt"]:::microservice
        aiProc["Procfile"]:::microservice
        model["yolov8n.pt"]:::microservice
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Mongo["MongoDB Atlas"]:::external
        Cloudinary["Cloudinary"]:::external
        Clerk["Clerk Auth"]:::external
        OSM["OpenStreetMap API"]:::external
    end

    %% Connections
    B -->|"HTTPS REST calls"| API
    API -->|"save image"| Cloudinary
    API -->|"POST /verifyImage"| AI
    AI -->|"verification result"| API
    API -->|"Mongoose queries"| Mongo
    API -->|"Clerk middleware"| Clerk
    API -->|"query Dustbin data"| Mongo
    API -->|"fetch map tiles"| OSM
    B -->|"Leaflet map requests"| OSM

    %% Click Events
    click main "https://github.com/aayushsinghal294/bingo/blob/main/client/src/main.jsx"
    click comp "https://github.com/aayushsinghal294/bingo/tree/main/client/src/components/"
    click pages "https://github.com/aayushsinghal294/bingo/tree/main/client/src/pages/"
    click services "https://github.com/aayushsinghal294/bingo/tree/main/client/src/services/"
    click utils "https://github.com/aayushsinghal294/bingo/blob/main/client/src/utils/api.js"
    click API "https://github.com/aayushsinghal294/bingo/blob/main/server/server.js"
    click controllers "https://github.com/aayushsinghal294/bingo/tree/main/server/controllers/"
    click routes "https://github.com/aayushsinghal294/bingo/tree/main/server/routes/"
    click models "https://github.com/aayushsinghal294/bingo/tree/main/server/models/"
    click scripts "https://github.com/aayushsinghal294/bingo/blob/main/server/Scripts/seedQuestionBank.js"
    click procBackend "https://github.com/aayushsinghal294/bingo/tree/main/server/Procfile"
    click pkg "https://github.com/aayushsinghal294/bingo/blob/main/server/package.json"
    click aiApp "https://github.com/aayushsinghal294/bingo/blob/main/ai_backend/app.py"
    click aiReq "https://github.com/aayushsinghal294/bingo/blob/main/ai_backend/requirements.txt"
    click aiProc "https://github.com/aayushsinghal294/bingo/tree/main/ai_backend/Procfile"
    click model "https://github.com/aayushsinghal294/bingo/blob/main/ai_backend/yolov8n.pt"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef microservice fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64
```
