Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hoangsonww/employee-management-fullstack-app
🧑🏻💻 This repository hosts the Employee Management Full-Stack App, built with a modern React frontend with a robust Java Spring Boot backend (the RJ-stack) & provides efficient data management and an interactive user experience!
https://github.com/hoangsonww/employee-management-fullstack-app
docker full-stack fullstack-development java javascript jsx maven mui-material react reactjs rest-api restful-api spring spring-boot spring-mvc springframework
Last synced: 25 days ago
JSON representation
🧑🏻💻 This repository hosts the Employee Management Full-Stack App, built with a modern React frontend with a robust Java Spring Boot backend (the RJ-stack) & provides efficient data management and an interactive user experience!
- Host: GitHub
- URL: https://github.com/hoangsonww/employee-management-fullstack-app
- Owner: hoangsonww
- License: mit
- Created: 2024-08-30T01:31:57.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2024-10-07T00:32:02.000Z (30 days ago)
- Last Synced: 2024-10-11T23:05:14.860Z (25 days ago)
- Topics: docker, full-stack, fullstack-development, java, javascript, jsx, maven, mui-material, react, reactjs, rest-api, restful-api, spring, spring-boot, spring-mvc, springframework
- Language: JavaScript
- Homepage: https://hoangsonww.github.io/Employee-Management-Fullstack-App/
- Size: 44.5 MB
- Stars: 14
- Watchers: 12
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Employee Management Full-Stack Application
## Table of Contents
- [Overview](#overview)
- [Key Technologies](#key-technologies)
- [User Interface](#user-interface)
- [File Structure](#file-structure)
- [API Endpoints](#api-endpoints)
- [Backend Setup](#backend-setup)
- [Prerequisites](#1-prerequisites)
- [Clone the Repository](#2-clone-the-repository)
- [Install Dependencies](#3-install-dependencies)
- [Configure the Application](#4-configure-the-application)
- [Start the Backend Server](#5-start-the-backend-server)
- [Access the API Endpoints](#6-access-the-api-endpoints)
- [API Documentation](#7-api-documentation)
- [Overview](#overview-1)
- [How to Access the API Documentation](#how-to-access-the-api-documentation)
- [Benefits of Using Swagger UI](#benefits-of-using-swagger-ui)
- [Frontend Setup](#frontend-setup)
- [Clone the Repository](#1-clone-the-repository)
- [Install Dependencies](#2-install-dependencies)
- [Set Up Environment Variables](#3-set-up-environment-variables)
- [Start the Development Server](#4-start-the-development-server)
- [Build for Production](#5-build-for-production)
- [Test the Application (Optional)](#6-test-the-application-optional)
- [Detailed Component Instructions](#detailed-component-instructions)
- [Containerization](#containerization)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
## Overview
The Employee Management System is a dynamic full-stack application that seamlessly combines cutting-edge and traditional technologies. By integrating a modern **React** frontend with a classic **Spring Boot** backend, this project demonstrates how new and established technologies can harmoniously work together to create a robust and efficient application for managing employee and department data!
## Key Technologies
- **React (Frontend)**: A modern JavaScript library for building user interfaces, providing a responsive and interactive experience.
- **React Router**: A routing library for React that enables navigation and URL handling in single-page applications.
- **Chart.js**: A JavaScript library for creating responsive and customizable charts and graphs.
- **Axios**: A promise-based HTTP client for making API requests.
- **Tailwind CSS**: A utility-first CSS framework for creating custom designs with minimal CSS.
- **Redux**: A predictable state container for managing application state.
- **Jest and React Testing Library**: Testing libraries for unit and integration testing React components.
- **Java Spring Boot (Backend)**: A powerful, established Java framework for building production-ready applications with Java, offering robust backend support and data management.
- **Spring Data JPA**: A part of the Spring Data project that makes it easy to implement JPA-based repositories.
- **Spring Boot Actuator**: A set of production-ready features that help monitor and manage the application.
- **Spring Hibernate**: An object-relational mapping (ORM) library for Java that provides a framework for mapping an object-oriented domain model to a relational database.
- **Spring Boot Starter Web**: A starter for building web applications, including RESTful, application, and WebSocket services.
- **Spring Boot Starter Data JPA**: A starter for using Spring Data JPA with Hibernate.
- **RESTful APIs**: Representational state transfer (REST) APIs for communication between the frontend and backend.
- **Java 11**: The latest LTS version of Java, providing long-term support and stability.
- **Docker**: A containerization platform for packaging applications and their dependencies.
- **MySQL**: A reliable relational database for structured data storage.
- **MongoDB**: A flexible NoSQL database for non-relational data.
- **Style Guides**: This project follows the following popular style guides to ensure clean and consistent code.
- **Airbnb JavaScript Style Guide**: A popular style guide for writing clean and consistent JavaScript code.
- **Google Java Style Guide**: A style guide for writing Java code that is readable and maintainable.
## User Interface
The frontend of the Employee Management System provides a user-friendly interface for managing employees and departments. It includes features for viewing, adding, editing, and deleting employees and departments. The app also includes visualizations for employee metrics such as growth over time and distribution by age range.
The frontend is also live at [https://employee-management-fullstack-app.vercel.app](https://employee-management-fullstack-app.vercel.app) for you to explore and interact with the application. Note that the backend is not hosted, so the API calls will not work and the data will not be present.
**Landing Page:**
**Dashboard Page:**
**Employee List Page:**
**Department List Page:**
**Edit Employee Form:**
**Footer:**
**Responsive Design Example - Dashboard Page:**
And many more features & pages to explore! Feel free to navigate through the application and test the various functionalities.
## API Endpoints
Here's a table listing all the RESTful API endpoints provided by this application:
| Endpoint | Method | Description |
|-------------------------|--------|-------------------------------------|
| `/api/employees` | GET | Get all employees |
| `/api/employees/{id}` | GET | Get an employee by ID |
| `/api/employees` | POST | Add a new employee |
| `/api/employees/{id}` | PUT | Update an employee by ID |
| `/api/employees/{id}` | DELETE | Delete an employee by ID |
| `/api/departments` | GET | Get all departments |
| `/api/departments/{id}` | GET | Get a department by ID |
| `/api/departments` | POST | Add a new department |
| `/api/departments/{id}` | PUT | Update a department by ID |
| `/api/departments/{id}` | DELETE | Delete a department by ID |
| `/swagger-ui.html` | GET | Access the Swagger UI documentation |
## File Structure
```
employee-management-app
│
├── docker-compose.yaml
│
├── .mvn
│ └── wrapper
│ └── maven-wrapper.properties
│
├── backend
│ ├── src
│ │ ├── main
│ │ │ ├── java
│ │ │ │ └── com
│ │ │ │ └── example
│ │ │ │ └── employeemanagement
│ │ │ │ ├── EmployeeManagementApplication.java
│ │ │ │ ├── config
│ │ │ │ │ └── CorsConfig.java
│ │ │ │ │ └── DataInitializer.java
│ │ │ │ ├── controller
│ │ │ │ │ ├── DepartmentController.java
│ │ │ │ │ └── EmployeeController.java
│ │ │ │ ├── model
│ │ │ │ │ ├── Department.java
│ │ │ │ │ └── Employee.java
│ │ │ │ ├── repository
│ │ │ │ │ ├── DepartmentRepository.java
│ │ │ │ │ └── EmployeeRepository.java
│ │ │ │ ├── service
│ │ │ │ │ └── DataInitializer.java
│ │ │ │ └── exception
│ │ │ │ └── ResourceNotFoundException.java
│ │ │ └── resources
│ │ │ ├── application.properties
│ │ │ └── data.sql
│ │ └── test
│ │ └── java
│ │ └── com
│ │ └── example
│ │ └── employeemanagement
│ │ └── EmployeeManagementApplicationTests.java
│ ├── .gitignore
│ └── pom.xml
│ └── compose.yaml
│
└── frontend
├── build
├── public
│ ├── index.html
│ └── favicon.ico
│ └── manifest.json
│ └── robots.txt
│ └── icon-192x192.webp
│ └── icon-512x512.webp
├── src
│ ├── components
│ │ ├── Dashboard.js
│ │ ├── EmployeeList.js
│ │ ├── EmployeeForm.js
│ │ ├── DepartmentList.js
│ │ ├── DepartmentForm.js
│ │ └── Navbar.js
│ ├── services
│ │ ├── employeeService.js
│ │ └── departmentService.js
│ ├── App.js
│ ├── index.js
│ ├── index.css
│ ├── reportWebVitals.js
│ └── App.css
│ └── theme.js
├── Dockerfile
├── postcss.config.js
├── tailwind.config.js
└── package.json
```
## Backend Setup
### 1. Prerequisites
Ensure that you have Java 11 installed on your local machine. If not, follow the instructions below:
- For MacOS:
```bash
brew install openjdk@11
export JAVA_HOME=/usr/local/opt/openjdk@11
```
- For Windows: Download OpenJDK 11 from [https://jdk.java.net/archive/](https://jdk.java.net/archive/) and follow the installation instructions.
- Also, ensure that MongoDB and MySQL are installed and running on your local machine.
### 2. Clone the Repository
```bash
git clone https://github.com/hoangsonww/Employee-Management-Fullstack-App.git
cd Employee-Management-Fullstack-App # Fix the paths if necessary
cd backend
```
### 3. Install Dependencies
First, ensure you have [Maven](https://maven.apache.org/) and [Java JDK](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) installed. Run the following command to install them:
- For MacOS:
```bash
brew install maven
```
- For Windows: Download Maven from [https://maven.apache.org/download.cgi](https://maven.apache.org/download.cgi) and follow the installation instructions.
Next, install the project dependencies:
```bash
mvn install
```
### 4. Configure the Application
Update `src/main/resources/application.properties` with your MySQL and MongoDB configuration:
```properties
# MySQL Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/employee_management
spring.datasource.username=root
spring.datasource.password=password
spring.jpa.hibernate.ddl-auto=update
# MongoDB Configuration
spring.data.mongodb.uri=mongodb://localhost:27017/employee_management
```
Feel free to change the database name, username, and password, and even add more configurations as needed.
### 5. Start the Backend Server
Before starting the server, ensure that MySQL and MongoDB are running and properly configured on your local machine!
Then, run the following command to start the Spring Boot application:
```bash
mvn spring-boot:run
```
The backend will be available at [http://localhost:8080](http://localhost:8080).
### 6. Access the API Endpoints
- **Get All Employees:**
```bash
curl -X GET http://localhost:8080/api/employees
```
- **Get Employee by ID:**
```bash
curl -X GET http://localhost:8080/api/employees/1
```
- **Get All Departments:**
```bash
curl -X GET http://localhost:8080/api/departments
```
- **Get Department by ID:**
```bash
curl -X GET http://localhost:8080/api/departments/1
```
- **Feel free to add more API endpoints as needed...**
### 7. API Documentation
#### Overview
This application also uses Swagger to provide an interactive API documentation interface. The Swagger UI allows developers to explore the available API endpoints, view detailed information about each endpoint, and test the endpoints directly from the browser.
#### How to Access the API Documentation
1. **Start the Backend Server**: Ensure that the backend server is running. You can start the server by navigating to the backend directory and running:
```bash
mvn spring-boot:run
```
2. **Open the Swagger UI**: Once the server is up and running, you can access the Swagger UI by navigating to the following URL in your web browser:
[http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)
This will open the Swagger interface where you can explore the API endpoints.
3. Alternatively, for those who need the raw OpenAPI JSON, it is available at:
[http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs)
4. **Explore the API Endpoints**:
- Use the sidebar or the search bar to navigate through the available API endpoints.
- Click on an endpoint to view its details, including the request method (GET, POST, PUT, DELETE), parameters, request body, and possible responses.
- You can also test the endpoints directly by clicking the **"Try it out"** button, providing the necessary input, and executing the request.
- If you have everything set up correctly, you should see the following Swagger UI interface:
#### Benefits of Using Swagger UI
- **Interactive Documentation**: Developers can easily understand and use the API.
- **Quick Testing**: Test the API endpoints directly from the browser without needing a separate tool.
- **Clear Communication**: Provides a standardized way of documenting your API, making it easier for others to understand and consume.
## Frontend Setup
### 1. Clone the Repository
```bash
git clone https://github.com/hoangsonww/Employee-Management-Fullstack-App.git
cd frontend
```
### 2. Install Dependencies
Ensure you have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed. Run the following command to install the required dependencies:
```bash
npm install
```
### 3. Set Up Environment Variables
Create a `.env` file in the root of your project if it doesn't already exist. Add the following environment variable:
```env
REACT_APP_API_URL=http://localhost:8080/api
```
### 4. Start the Development Server
Run the following command to start the React development server:
```bash
npm start
```
The frontend will be available at [http://localhost:3000](http://localhost:3000).
### 5. Build for Production
To create a production build of your application, run:
```bash
npm run build
```
The build files will be generated in the `build` directory. You can deploy these files to your production server.
### 6. Test the Application (Optional)
To run tests for the frontend application, use the following command:
```bash
npm test
```
**NOTE: You might need different IDEs for the backend and the frontend. FYI, I used IntelliJ IDEA for the backend and Webstorm for the frontend.**
## Detailed Component Instructions
### `Dashboard.js`
Displays various metrics related to employees, such as total employee count, average age, employee growth over time, and distribution by age range. It uses `react-chartjs-2` to render bar charts.
### `EmployeeList.js`
Shows a list of employees with options to search, paginate, and delete entries. Includes a link to add a new employee and edit existing employees.
### `EmployeeForm.js`
Provides a form for adding or editing employee details. Fetches departments to populate the department dropdown. Uses `useParams` to determine if it's in edit mode or add mode.
### `DepartmentList.js`
Displays a list of departments with options to search, paginate, and delete entries. Includes a link to add a new department and edit existing departments.
### `DepartmentForm.js`
Provides a form for adding or editing department details.
### `Navbar.js`
The navigation bar component that includes links to various pages such as Dashboard, Employees, and Departments. Highlights the currently active page.
## Containerization
If you'd also like to containerize the project, the project also includes the `dockerfile` and `docker-compose.yaml` files for containerization. You can build and run the application in a Docker container using the following command:
```bash
docker compose up --build
```
This command will build the Docker images for the frontend and backend, create containers, and start the application. Feel free to view them in Docker Desktop.
## Troubleshooting
### Backend Issues
- **`Could not autowire` Errors**: Ensure that all dependencies are correctly defined in the `pom.xml` and that the repository interfaces are located in the correct package structure.
- **`Exception opening socket` for MongoDB**: Verify that MongoDB is running and accessible at `localhost:27017`. Check MongoDB logs for any connection issues.
- **`Build failed`**: Ensure that you are using Java 11 and that all dependencies are correctly installed. Check the `pom.xml` file for any missing dependencies.
- Regardless of the error, perhaps you can try running the following commands to clean and rebuild the project:
```bash
mvn clean install
```
If the issue persists, you can run Maven with more detailed logging to identify the problem:
```bash
mvn -X spring-boot:run
```
### Frontend Issues
- **Error: Cannot read properties of undefined (reading 'id')**: Ensure that the `employee` object in `EmployeeForm` is correctly initialized and that the `id` parameter is correctly passed. Check the `getEmployeeById` and `updateEmployee` functions for proper handling of data.
- **Chart Issues**: Ensure `Chart.js` and `react-chartjs-2` are correctly installed and configured. Verify that the chart data passed to components is in the correct format.
- Regardless of the error, perhaps you can try running the following commands to clean and rebuild the project:
```bash
npm install
```
If the issue persists, you can run the React development server with more detailed logging to identify the problem:
```bash
npm start --verbose
```
## Contributing
If you'd like to contribute to the project, please fork the repository and submit a pull request with your changes. Ensure that you follow the project's coding standards and include relevant tests for new features.
## License
This project is licensed under the **MIT License.** See the [LICENSE](LICENSE) file for details.
## Contact
For any questions or issues, please contact [[email protected]](mailto:[email protected]).
---
Thank you for checking out the **Employee Management Full-Stack Application!** Feel free to use this project for your own learning or development purposes.
Created with ❤️ by [Son Nguyen](https://github.com/hoangsonww) in 2024.
---
**[⬆ Back to Top](#employee-management-full-stack-application)**