# vinhtranphuc/spring-react-social architecture

> Architecture diagram of the GitHub repository vinhtranphuc/spring-react-social, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinhtranphuc/spring-react-social
- Repository: https://github.com/vinhtranphuc/spring-react-social

## Overview

##### Project type and purpose
- This is a full-stack web application demo showcasing social login via OAuth2.
- Frontend: React single-page-app (“react-social”)
- Backend: Spring Boot REST API with Spring Security and OAuth2 support (“spring-social”)
- Purpose: Allow users to sign up/login via username/password or Google/Facebook/GitHub OAuth2, persist users in MySQL, issue JWTs.

##### File structure
- react-social/
- public/: static HTML, manifest
- src/app: root App component & routing
- src/common: shared UI components (header, loading, PrivateRoute)
- src/home, src/user/{login, signup, profile, oauth2}: page components
- src/util/APIUtils.js: REST client wrappers
- spring-social/
- src/main/java/.../config: AppProperties, WebMvcConfig, SecurityConfig
- src/main/java/.../controller: REST endpoints (AuthController, UserController, OAuth2 callback logic)
- src/main/java/.../security: Spring Security filters, TokenProvider, OAuth2 handlers, CurrentUser annotation
- src/main/java/.../repository: JPA UserRepository
- src/main/java/.../model & payload: domain and DTOs
- src/main/resources/application.yml: DB and OAuth2 provider properties

##### README for additional insights
- MySQL database setup
- application.yml contains JDBC and OAuth2 client IDs/secrets
- Frontend served on localhost:3000, backend on 8080
- OAuth2 redirect URIs configured on providers

##### Main components and interactions
a. Components
- Browser / React Client (SPA at http://localhost:3000)
- Static Web Server (serving index.html, JS, CSS)
- REST API Server (Spring Boot on http://localhost:8080)
- MySQL Database (spring_social schema)
- OAuth2 Providers (Google, Facebook, GitHub)
b. Relationships
- Browser → React SPA HTTP GET (initial page load)
- React SPA ↔ REST API HTTP(S) calls /api/** for login, signup, profile, data
- SPA triggers OAuth2 login → Redirect browser to Provider’s auth URL
- OAuth2 Provider → Redirect back to /oauth2/callback/{provider} on API Server
- API Server uses OAuth2 filter chain → obtains user info → persists/updates in MySQL
- API Server issues JWT (in HTTP-Only cookie or JSON) → Browser stores token
- Browser includes JWT in Authorization header for protected REST calls
c. Architectural patterns & design principles
- Three-tier architecture: Presentation (React), Application (Spring Boot REST + Security), Data (MySQL)
- RESTful API with stateless JWT authentication
- OAuth2 Authorization Code grant flow
- Modular code organization: controllers, services, repositories, security filters
d. Key technologies
- Frontend: React, react-router (PrivateRoute), Axios/ fetch wrappers (APIUtils)
- Backend: Spring Boot, Spring MVC, Spring Security, OAuth2Client, Spring Data JPA, MySQL
- Security: JWT, CookieUtils, TokenAuthenticationFilter, CustomOAuth2UserService

1. Start by sketching three horizontal layers: Client, Server, Data/External.
3. In the Server layer, group Spring Boot modules:
- SecurityConfig & Filters (TokenAuthenticationFilter, OAuth2 handlers)
- Controllers (AuthController, UserController)
- Services (CustomOAuth2UserService, TokenProvider)
- Repositories (UserRepository)
4. In the Data/External layer, place MySQL and OAuth2 Providers.
- Browser → React SPA assets (static serve)
- React SPA ↔ Spring API (REST calls with JWT)
- Spring API ↔ MySQL (JDBC/JPA)
- Browser ↔ OAuth2 Providers (redirects, callback)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (React SPA)"
        Browser["Browser / React SPA"]:::frontend
        Static["Static Assets (index.html, JS, CSS)"]:::frontend
        SPACommon["Shared UI Components"]:::frontend
        Pages["Page Components"]:::frontend
        APIUtils["APIUtils.js"]:::frontend
    end

    %% Server Layer
    subgraph "Server (Spring Boot API)"
        Entry["SpringSocialApplication.java"]:::backend
        subgraph "Config"
            AppProps["AppProperties.java"]:::backend
            WebMVC["WebMvcConfig.java"]:::backend
            SecConfig["SecurityConfig.java"]:::backend
        end
        subgraph "Controllers"
            AuthC["AuthController.java"]:::backend
            UserC["UserController.java"]:::backend
        end
        subgraph "Security"
            TokenFilter["TokenAuthenticationFilter.java"]:::backend
            TokenProv["TokenProvider.java"]:::backend
            RestEntry["RestAuthenticationEntryPoint.java"]:::backend
            CurrentUserAnno["CurrentUser.java"]:::backend
            subgraph "OAuth2"
                OAuthService["CustomOAuth2UserService.java"]:::backend
                AuthReqRepo["HttpCookieOAuth2AuthorizationRequestRepository.java"]:::backend
                SuccessHandler["OAuth2AuthenticationSuccessHandler.java"]:::backend
                FailureHandler["OAuth2AuthenticationFailureHandler.java"]:::backend
                ProviderUser["Provider User Info Classes"]:::backend
            end
        end
        subgraph "Persistence"
            UserRepo["UserRepository.java"]:::backend
            UserModel["User.java / AuthProvider.java"]:::backend
            Payload["Request/Response DTOs"]:::backend
            AppYml["application.yml"]:::backend
        end
    end

    %% Data & External Layer
    subgraph "Data & External"
        MySQL["MySQL Database"]:::external
        subgraph "OAuth2 Providers"
            Google["Google"]:::external
            Facebook["Facebook"]:::external
            GitHub["GitHub"]:::external
        end
    end

    %% Connections
    Browser -->|"GET /"| Static
    Browser -->|"XHR /api/auth/**"| AuthC
    Browser -->|"XHR /api/user/**"| UserC
    AuthC -->|"uses filters"| TokenFilter
    AuthC -->|"generates token"| TokenProv
    TokenProv -->|"persists user"| UserRepo
    UserRepo -->|"JPA/JDBC"| MySQL
    Browser -->|"302 Redirect to OAuth2"| Google
    Google -->|"302 Callback to /oauth2/callback"| AuthC
    AuthC -->|"JWT response"| Browser
    Browser -->|"Authorized XHR /api/user/me"| UserC

    %% Click Events - Client
    click Browser "https://github.com/vinhtranphuc/spring-react-social/tree/master/react-social/src/app"
    click Static "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/public/index.html"
    click SPACommon "https://github.com/vinhtranphuc/spring-react-social/tree/master/react-social/src/common"
    click Pages "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/src/home/Home.js"
    click Pages "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/src/user/login/Login.js"
    click Pages "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/src/user/signup/Signup.js"
    click Pages "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/src/user/profile/Profile.js"
    click Pages "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/src/user/oauth2/OAuth2RedirectHandler.js"
    click APIUtils "https://github.com/vinhtranphuc/spring-react-social/blob/master/react-social/src/util/APIUtils.js"

    %% Click Events - Server
    click Entry "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/SpringSocialApplication.java"
    click AppProps "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/config/AppProperties.java"
    click WebMVC "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/config/WebMvcConfig.java"
    click SecConfig "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/config/SecurityConfig.java"
    click AuthC "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/controller/AuthController.java"
    click UserC "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/controller/UserController.java"
    click TokenFilter "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/TokenAuthenticationFilter.java"
    click TokenProv "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/TokenProvider.java"
    click RestEntry "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/RestAuthenticationEntryPoint.java"
    click CurrentUserAnno "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/CurrentUser.java"
    click OAuthService "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/oauth2/CustomOAuth2UserService.java"
    click AuthReqRepo "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/oauth2/HttpCookieOAuth2AuthorizationRequestRepository.java"
    click SuccessHandler "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/oauth2/OAuth2AuthenticationSuccessHandler.java"
    click FailureHandler "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/security/oauth2/OAuth2AuthenticationFailureHandler.java"
    click ProviderUser "https://github.com/vinhtranphuc/spring-react-social/tree/master/spring-social/src/main/java/com/example/springsocial/security/oauth2/user"
    click UserRepo "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/repository/UserRepository.java"
    click UserModel "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/java/com/example/springsocial/model/User.java"
    click Payload "https://github.com/vinhtranphuc/spring-react-social/tree/master/spring-social/src/main/java/com/example/springsocial/payload"
    click AppYml "https://github.com/vinhtranphuc/spring-react-social/blob/master/spring-social/src/main/resources/application.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6
    classDef backend fill:#DFFFE0,stroke:#228B22
    classDef external fill:#FFF0D0,stroke:#FF8C00
```
