# god3tier/heap_project architecture

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

- Interactive diagram: https://gitdiagram.com/god3tier/heap_project
- Repository: https://github.com/god3tier/heap_project

## Overview

##### Project type and purpose
- This is a full-stack web application called “Up2u” that helps users find food stalls near SMU based on filters (price, cuisine, rating, proximity).
- Frontend: React + Vite single-page application (SPA) deployed on Vercel.
- Backend: Spring Boot (Java 21, Maven) REST API with JWT authentication.
- Database: relational (likely PostgreSQL or another SQL DB via JDBC).
- External service: Google Maps JavaScript & Geocode APIs for map display and geolocation.

##### File structure
- Top-level:
- backend/ → Spring Boot project (standard Maven layout, controllers, services, repos, security config)
- frontend/up2u-react/ → React + Vite app (components, pages, assets, env configuration)
- Backend layers:
- controller (AuthApiController, StallMealController, UserReviewController)
- service (AuthServiceImpl, StallServiceImpl, UserReviewServiceImpl)
- repo (JPA repositories for User, Stall, Meal, Review)
- security (filters, JWT service, authentication handlers)
- config (ModelMapper, SecurityConfig)
- Frontend modules:
- pages (home, login, signup, search, maps, reviews, list-reviews, about-us)
- components (NavBar, Layout, RatingDropdown, StallsDropdown)
- assets & styles for UI
- Deployment/dev:
- backend Dockerfile + compose.yaml
- frontend Vercel config
- environment files (.env, .env.local)

##### README for insights
- Backend requires a .env with DB credentials, SECRET_PASSCODE, FRONTEND_URL/PORT.
- Frontend uses VITE_BACKEND_URL and VITE_MAPS_API.
- Illustrates integration points: SPA ←→ REST API ←→ Database and Google Maps.

a. Main components
- Client (Browser) running React SPA
- Frontend server (Vercel or local dev server)
- API Gateway / Load Balancer (optional, for production)
- Spring Boot Application (REST API)
- Relational Database (PostgreSQL)
- External Google Maps APIs (JavaScript & Geocoding)
b. Relationships & interactions
1. User interacts with React SPA → SPA issues HTTP(S) calls to Spring Boot REST endpoints (e.g., /api/stalls, /api/auth/login, /api/reviews).
2. Spring Boot controller → service → repository → DB.
3. Auth flow: SPA sends credentials → AuthController → JwtService → issues JWT → SPA stores token → includes in Authorization header on subsequent requests.
4. Maps integration: SPA loads Google Maps JS API using VITE_MAPS_API key, performs geocoding or map rendering in browser.
c. Architectural patterns
- Frontend: Component-based SPA, client-side routing.
- Backend: Layered (Controller → Service → Repository), JWT-based stateless authentication, ModelMapper for DTO mapping, Spring Security filter chain.
- Database per service (monolithic data store).
- Dockerized backend for consistent deployment.
d. Key technologies
- React, Vite, Node.js, npm
- Spring Boot, Spring Security, JWT
- Maven, Java 21
- PostgreSQL (or similar)
- Docker, Docker Compose
- Google Maps JavaScript & Geocode APIs

##### Don’t overthink—capture all components
- Frontend: Browser, Vercel, React pages & components.
- Backend: Docker container, Spring Boot layers (controllers, services, repos), security filter.
- Database: relational store.
- External: Google Maps JS & Geocoding API.
- Infrastructure: optional load balancer, Docker Compose network.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Zone
    subgraph "Client Zone"
        direction TB
        Browser["User Browser"]:::client
    end

    %% Frontend Hosting
    subgraph "Frontend Hosting (Vercel / Dev Server)"
        direction TB
        ReactSPA["React SPA"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
        EnvLocal[".env.local"]:::frontend
        subgraph "Entry & Styles"
            direction TB
            EntryPoint["main.jsx"]:::frontend
            GlobalStyles["App.css & index.css"]:::frontend
        end
        subgraph "Components"
            direction TB
            Layout["Layout.jsx"]:::frontend
            NavBar["NavBar.jsx"]:::frontend
            RatingDropdown["RatingDropdown.jsx"]:::frontend
            StallsDropdown["StallsDropdown.jsx"]:::frontend
        end
        subgraph "Pages"
            direction TB
            HomePage["home.jsx"]:::frontend
            LoginPage["login.jsx"]:::frontend
            SignupPage["signup.jsx"]:::frontend
            SearchPage["search.jsx"]:::frontend
            MapsPage["maps.jsx"]:::frontend
            ReviewsPage["reviews.jsx"]:::frontend
            ListReviewsPage["list-reviews.jsx"]:::frontend
            AboutUsPage["about-us.jsx"]:::frontend
        end
    end

    %% Backend Zone
    subgraph "Backend Zone (Docker / JVM)"
        direction TB
        LoadBalancer["API Gateway / Load Balancer"]:::backend
        SpringBootAPI["Spring Boot API"]:::backend
        subgraph "Controllers"
            direction TB
            AuthController["AuthApiController.java"]:::backend
            StallMealController["StallMealController.java"]:::backend
            UserReviewController["UserReviewController.java"]:::backend
        end
        subgraph "Services"
            direction TB
            AuthServiceImpl["AuthServiceImpl.java"]:::backend
            StallServiceImpl["StallServiceImpl.java"]:::backend
            UserReviewServiceImpl["UserReviewServiceImpl.java"]:::backend
            JwtService["JwtService.java"]:::backend
        end
        subgraph "Security"
            direction TB
            SecurityConfig["SecurityConfig.java"]:::backend
            SecurityFilter["SecurityAuthenticationFilter.java"]:::backend
        end
        subgraph "Repositories & Entities"
            direction TB
            UserRepo["UserRepo.java"]:::backend
            StallRepo["StallRepo.java"]:::backend
            MealRepo["MealRepo.java"]:::backend
            ReviewRepo["ReviewRepo.java"]:::backend
        end
        ModelMapperConfig["ModelMapperConfig.java"]:::backend
        ApplicationStarter["MyApplication.java"]:::backend
        ApplicationProperties["application.properties"]:::backend
        Dockerfile["Dockerfile"]:::backend
        ComposeYAML["compose.yaml"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Database["PostgreSQL DB"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleMaps["Google Maps JS & Geocode API"]:::external
    end

    %% Connections
    Browser -->|"navigates to"| ReactSPA
    ReactSPA -->|"HTTPS /api/**"| LoadBalancer
    LoadBalancer -->|"forwards to"| SpringBootAPI
    SpringBootAPI -->|"JPA/JDBC"| Database
    ReactSPA -->|"Maps & Geocoding calls"| GoogleMaps

    SpringBootAPI --> AuthController
    SpringBootAPI --> StallMealController
    SpringBootAPI --> UserReviewController

    AuthController --> AuthServiceImpl
    StallMealController --> StallServiceImpl
    UserReviewController --> UserReviewServiceImpl

    AuthServiceImpl --> JwtService
    SpringBootAPI --> SecurityFilter
    SecurityFilter --> SecurityConfig

    AuthServiceImpl --> UserRepo
    StallServiceImpl --> StallRepo
    StallServiceImpl --> MealRepo
    UserReviewServiceImpl --> ReviewRepo

    SpringBootAPI --> ModelMapperConfig
    SpringBootAPI --> ApplicationProperties
    SpringBootAPI --> ApplicationStarter

    SpringBootAPI --> Dockerfile
    SpringBootAPI --> ComposeYAML

    %% Click Events - Frontend
    click ReactSPA "https://github.com/god3tier/heap_project/tree/main/frontend/up2u-react/"
    click ViteConfig "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/vite.config.js"
    click EnvLocal "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/.env.local"
    click EntryPoint "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/main.jsx"
    click GlobalStyles "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/index.css"
    click GlobalStyles "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/App.css"
    click Layout "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/components/Layout.jsx"
    click NavBar "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/components/NavBar.jsx"
    click RatingDropdown "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/components/RatingDropdown.jsx"
    click StallsDropdown "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/components/StallsDropdown.jsx"
    click HomePage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/home.jsx"
    click LoginPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/login.jsx"
    click SignupPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/signup.jsx"
    click SearchPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/search.jsx"
    click MapsPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/maps.jsx"
    click ReviewsPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/reviews.jsx"
    click ListReviewsPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/list-reviews.jsx"
    click AboutUsPage "https://github.com/god3tier/heap_project/blob/main/frontend/up2u-react/src/pages/about-us.jsx"

    %% Click Events - Backend
    click ApplicationStarter "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/MyApplication.java"
    click SecurityConfig "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/config/SecurityConfig.java"
    click ModelMapperConfig "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/config/ModelMapperConfig.java"
    click AuthController "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/controller/AuthApiController.java"
    click StallMealController "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/controller/StallMealController.java"
    click UserReviewController "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/controller/UserReviewController.java"
    click AuthServiceImpl "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/service/AuthServiceImpl.java"
    click StallServiceImpl "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/service/StallServiceImpl.java"
    click UserReviewServiceImpl "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/service/UserReviewServiceImpl.java"
    click UserRepo "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/user/UserRepo.java"
    click StallRepo "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/stalls/StallRepo.java"
    click MealRepo "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/meal/MealRepo.java"
    click ReviewRepo "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/review/ReviewRepo.java"
    click JwtService "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/security/service/JwtService.java"
    click SecurityFilter "https://github.com/god3tier/heap_project/blob/main/backend/src/main/java/heap/application/security/filter/SecurityAuthenticationFilter.java"
    click ApplicationProperties "https://github.com/god3tier/heap_project/blob/main/backend/src/main/resources/application.properties"
    click Dockerfile "https://github.com/god3tier/heap_project/tree/main/backend/Dockerfile"
    click ComposeYAML "https://github.com/god3tier/heap_project/blob/main/backend/compose.yaml"

    %% Styles
    classDef client fill:#D6E9FE,stroke:#4A90E2,color:#000
    classDef frontend fill:#DFF5E1,stroke:#28A745,color:#000
    classDef backend fill:#FFF4E5,stroke:#FFB400,color:#000
    classDef db fill:#F9E2E7,stroke:#E83E8C,color:#000
    classDef external fill:#ECECEC,stroke:#6C757D,color:#000
```
