diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..6f649ab --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,38 @@ +## Description + +Please include a summary of the changes and the related issue. Please also include relevant motivation and context. + +Fixes # (issue) + +## Type of change + +Please delete options that are not relevant. + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Refactoring (improves structure without changing external behavior) +- [ ] Code style update (formatting, local variables) +- [ ] Build related changes +- [ ] CI/CD related changes +- [ ] Other (please describe): + +## Checklist + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and pulled down recently +- [ ] I have verified my changes work in the staging environment (if applicable) +- [ ] I have updated the README.md if applicable + +## Screenshots (if applicable): + +## Additional context + +Add any other context about the problem here. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ + diff --git a/README.md b/README.md index 75e43f2..a8710ad 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,238 @@ # GreenCode -GreenCode is an API core system designed to support esm_greencode . -It consists of a **Spring Boot backend API** +GreenCode is an API core system designed to support esm_greencode. +It consists of a **Spring Boot backend API** with a React frontend. --- ## ๐Ÿš€ Features ### Backend (Spring Boot) -- RESTful API +- RESTful API endpoints - JWT/OAuth authentication - PostgreSQL database support -- Centralised configuration (`config/`, `.env`) +- Centralized configuration (`config/`, `.env`) - Dockerized for easy deployment - Swagger/OpenAPI documentation +### Frontend (React) +- Modern user interface +- Responsive design +- Integration with GreenCode API +- State management + +--- ## ๐Ÿ“ Project Structure +``` GreenCode/ โ”œโ”€โ”€ src/ # Spring Boot source code -โ”œโ”€โ”€ config/ # external configuration & scripts -โ”œโ”€โ”€ docs/ # architecture, API docs -โ”œโ”€โ”€ greencode-frontend/ # React frontend (new) -โ”œโ”€โ”€ pom.xml # Maven build file -โ””โ”€โ”€ docker-compose.yml # Docker orchestration +โ”œโ”€โ”€ config/ # External configuration & scripts +โ”œโ”€โ”€ docs/ # Architecture, API documentation +โ”œโ”€โ”€ greencode-frontend/ # React frontend application +โ”œโ”€โ”€ pom.xml # Maven build configuration +โ””โ”€โ”€ docker-compose.yml # Docker orchestration file +``` + +--- + +## ๐Ÿ› ๏ธ Technology Stack + +### Backend +- **Language:** Java 17 +- **Framework:** Spring Boot 3.x +- **Database:** PostgreSQL with Spring Data JPA +- **Security:** Spring Security with JWT/OAuth +- **API Documentation:** Swagger/OpenAPI 3.0 +- **Build Tool:** Maven + +### Frontend +- **Library:** React 18 +- **Styling:** CSS3 with responsive design +- **HTTP Client:** Axios +- **Routing:** React Router v6 +- **State Management:** React Context API + +### DevOps & Infrastructure +- **Containerization:** Docker +- **Orchestration:** Docker Compose +- **Version Control:** Git +- **CI/CD:** GitHub Actions (planned) + +--- + +## โš™๏ธ Setup and Installation + +### Prerequisites +- Java 17 or higher (OpenJDK or Oracle JDK) +- Maven 3.8+ +- Node.js 18+ and npm (for frontend) +- Docker and Docker Compose v2 +- PostgreSQL 13+ + +### Backend Setup + +1. **Clone the repository:** + ```bash + git clone https://github.com/Bienvenu-crypto/GreenCode.git + cd GreenCode + ``` + +2. **Configure environment variables:** + ```bash + cp env.example .env + ``` + Edit `.env` with your configuration: + ```env + # Database + SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/greencode + SPRING_DATASOURCE_USERNAME=your_username + SPRING_DATASOURCE_PASSWORD=your_password + + # JWT Security + JWT_SECRET=your_strong_secret_key_here + JWT_EXPIRATION_MS=86400000 + + # Server + SERVER_PORT=8080 + ``` + +3. **Build the backend:** + ```bash + ./mvnw clean install + ``` + +4. **Run the backend:** + ```bash + ./mvnw spring-boot:run + ``` + The API will be available at `http://localhost:8080`. + +### Frontend Setup + +1. **Navigate to the frontend directory:** + ```bash + cd greencode-frontend + ``` + +2. **Install dependencies:** + ```bash + npm install + ``` + +3. **Configure API connection:** + Create `.env` in the frontend directory: + ```env + REACT_APP_API_URL=http://localhost:8080/api + ``` + +4. **Start the development server:** + ```bash + npm start + ``` + The frontend will be available at `http://localhost:3000`. + +### Docker Setup (Recommended for Development) + +1. **Ensure Docker and Docker Compose are installed.** + +2. **Build and start all services:** + ```bash + docker-compose up --build + ``` + +3. **Access the applications:** + - Backend API: `http://localhost:8080` + - Frontend: `http://localhost:3000` + - API Documentation: `http://localhost:8080/swagger-ui.html` + +4. **To stop and clean up:** + ```bash + docker-compose down + ``` + +--- + +## ๐Ÿ“š API Documentation + +Once the backend is running, access the interactive API documentation: + +- **Swagger UI:** http://localhost:8080/swagger-ui.html +- **OpenAPI JSON:** http://localhost:8080/v3/api-docs +- **OpenAPI YAML:** http://localhost:8080/v3/api-docs/yaml + +--- + +## ๐Ÿงช Testing + +### Backend Tests +```bash +# Run all tests +./mvnw test + +# Run only unit tests +./mvnw test -DskipITs + +# Run only integration tests +./mvnw verify -Dskip.unit.tests +``` + +### Frontend Tests +```bash +# Run tests +npm test + +# Run tests in watch mode +npm test -- --watch + +# Run tests with coverage +npm test -- --coverage +``` + +--- + +## ๐Ÿค Contributing + +We welcome contributions from the community! Please follow these guidelines: + +1. **Fork the repository** on GitHub +2. **Create a feature branch** from `main`: + ```bash + git checkout -b feature/amazing-feature + ``` +3. **Make your changes** following our coding standards +4. **Add tests** for new functionality +5. **Ensure all tests pass** +6. **Commit your changes** with descriptive messages +7. **Push to your fork** and submit a pull request + +### Pull Request Process +1. Update README.md with details of changes if applicable +2. The PR will be reviewed by maintainers +3. Address any feedback from reviewers +4. Once approved, your PR will be merged + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. + +--- + +## ๐Ÿ“„ License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +--- + +## ๐Ÿ“ž Contact + +For questions, support, or collaboration inquiries: +- Open an issue on this repository +- Contact the maintainers through GitHub Discussions +- Email: oss@bos-community.org (if applicable) + +--- +## ๐Ÿ™ Acknowledgments +- Bugema Open Source Community (BOSC) for project stewardship +- All contributors who have helped shape GreenCode +- The open-source community for tools and inspiration