{"id":24236862,"url":"https://github.com/luiscvillarreall/restcalculator","last_synced_at":"2026-04-12T02:36:35.962Z","repository":{"id":270900525,"uuid":"911688109","full_name":"LuiscVillarrealL/restcalculator","owner":"LuiscVillarrealL","description":"Project for RESTful API for calculator With kafka Messaging","archived":false,"fork":false,"pushed_at":"2025-01-29T23:06:41.000Z","size":497,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-04T14:49:50.758Z","etag":null,"topics":["angular","kafka","restful-api","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LuiscVillarrealL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-03T15:57:58.000Z","updated_at":"2025-01-29T23:06:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"c9afbda2-5197-4a82-8236-0fe25b4c5354","html_url":"https://github.com/LuiscVillarrealL/restcalculator","commit_stats":null,"previous_names":["luiscvillarreall/restcalculator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/LuiscVillarrealL/restcalculator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuiscVillarrealL%2Frestcalculator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuiscVillarrealL%2Frestcalculator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuiscVillarrealL%2Frestcalculator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuiscVillarrealL%2Frestcalculator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LuiscVillarrealL","download_url":"https://codeload.github.com/LuiscVillarrealL/restcalculator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuiscVillarrealL%2Frestcalculator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273728151,"owners_count":25157136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","kafka","restful-api","spring-boot"],"created_at":"2025-01-14T19:49:05.389Z","updated_at":"2026-04-12T02:36:35.910Z","avatar_url":"https://github.com/LuiscVillarrealL.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RestCalculator – Spring Boot Multi-Module Project\n\n## Introduction\nRestCalculator is a Spring Boot multi-module project designed to provide a RESTful API for performing various calculator operations. The project leverages Kafka for messaging and follows a modular architecture for scalability and maintainability. An Angular-based frontend interacts with the backend services.\n\n![Alt Text](./images/Calculator.drawio.png)\n\n### Project Structure\n- **Parent Module (`restcalculator`)** – Root module managing dependencies and submodules.\n- **Common Module (`common`)** – Shared classes and utilities.\n- **Calculator Module (`calculator`)** – Core business logic for calculator operations.\n- **Rest Module (`rest`)** – Exposes the calculator functionality via RESTful APIs.\n- **Angular Frontend (`calculator-frontend`)** – Provides a simple user interface.\n\n## Table of Contents\n- [Installation](#installation)\n- [Modules](#modules)\n- [Features](#features)\n- [Other Technical Features](#other-technical-features)\n- [Dependencies](#dependencies)\n- [Configuration](#configuration)\n- [REST API Endpoints](#rest-api-endpoints)\n- [Kafka Messaging Flow](#kafka-messaging-flow)\n- [Extras](#extras)\n- [Future Features](#future-features)\n\n\n## Installation\n### Prerequisites\n- **Java 21** or higher\n- **Maven 3.x**\n- **Docker and Docker Compose**\n\nTo run Docker containers, ensure the following are installed and properly configured on your system:\n\n1. **Docker**:\n   - Install Docker: Follow the instructions at [Docker Installation Guide](https://docs.docker.com/get-docker/).\n   - Verify Docker is installed:\n     ```bash\n     docker --version\n     ```\n   - Ensure the Docker daemon is running.\n\n2. **Docker Compose** :\n   - Install Docker Compose: Follow the instructions at [Docker Compose Installation Guide](https://docs.docker.com/compose/install/).\n   - Verify Docker Compose is installed:\n     ```bash\n     docker-compose --version\n     ```\n\n3. **Resources for Docker**:\n   - Allocate sufficient CPU, memory, and disk space to Docker:\n     - Recommended: At least **2 CPUs**, **4GB RAM**, and **10GB disk space**.\n   - Configure these resources in the Docker Desktop application (if using Docker Desktop).\n\n4. **Kafka and Zookeeper Ports**:\n   - Ensure the following ports are available for Kafka, Zookeeper, and services:\n     - `2181`, `9092`, `29092`, `8081`, `8085`, and `8086`.\n\n---\n\n### Build Instructions\nClone the repository and navigate to the root directory of the project:\n```bash\ngit clone \u003crepository-url\u003e\ncd restcalculator\n```\n\n\n\n#### 1. Using Docker to build project\n\n\n\n\nTo build and run:\n```bash\ndocker-compose up --build\n```\n\nTo stop the containers:\n```bash\ndocker-compose down\n```\n\n#### 2. Build project locally\nIf Docker is not used to build the entire project (docker is still needed for kafka messages), make the following adjustments:\n\n##### Configuration Changes\nIn the application.properties file of the rest and calculator modules:\n\nReplace the ```broker:29092``` reference with ```localhost:9092``` in the ```application.properties``` of the ```rest``` and ```calculator``` modules:\n```bash\nspring.kafka.bootstrap-servers=localhost:9092\n```\n##### Using Local docker-compose\n\nUse the ```dockerfile.local``` file instead of the default Dockerfile. (change ```docker-compose.yml.local``` to ```docker-compose``` and the original\n```docker-compose``` to ```docker-compose.x(any name)```\n\n##### Install from parent\n```bash\nmvn clean install\n```\n\n##### Start Kafka and Zookeeper with docker\nand run on docker\n```bash\ndocker-compose up \n```\n\n##### Build and run the services\n\n* For the rest module:\n\n```bash\ncd rest\nmvn spring-boot:run\n\n```\n\n\n* For the calculator module:\nfrom parent:\n```bash\ncd calculator\nmvn spring-boot:run\n```\n\n## Modules\n### 1. Parent Module (```restcalculator```)\n* Aggregates all modules.\n* Manages dependency versions and Maven build configurations.\n\n### 2. Common Module (common)\n* Contains shared utilities and common classes.\n\n### 3. Calculator Module (calculator)\n* Implements core arithmetic logic and decision-making for calculations.\n\n### 4. Rest Module (rest)\n* Provides REST endpoints for calculator functions and forwards requests to the calculator module via Kafka.\n\n### 5. Angular Frontend (calculator-frontend) (extra)\n* A simple Angular frontend that interacts with the REST API.\n* Dockerized using nginx for deployment.\n\n## Features\n* Modular architecture with clearly separated concerns.\n* RESTful API with Swagger/OpenAPI integration.\n* Kafka integration for messaging and event-driven architecture.\n* Angular-based frontend for interacting with the API.\n* Test containers for integration testing.\n\n## Other Technical Features\n#### 1. Logging with SLF4J\n* The project uses SLF4J (Simple Logging Facade for Java) with Logback as the logging implementation.\n\n* Logging is configured to write logs both to the console and a file for better traceability and persistence.\n\n* The log file is located at:\n\n\t* ```logs/application.log``` (relative to the working directory where the application is run).\n* Example of a log entry:\n\t\t\n\t```2025-01-07T21:51:45 [org.springframework.kafka.KafkaListenerEndpointContainer#0-0-C-1] LEVEL=INFO TRACEID=272daf88-9168-4b66-9ad3-042c70b5a32f | Sending message from calculation-result-topic topic CalculationResponse(requestId=272daf88-9168-4b66-9ad3-042c70b5a32f, result=0.2, error=null)```\n\n#### 2. Unique Identifiers (RequestId)\n* Each request is assigned a unique identifier (RequestId) to:\n\t* Enable better tracking of requests across services.\n\t* Simplify debugging and correlation between logs and messages.\n\t\n* RequestId Propagation:\n\t* The RequestId is passed between services via HTTP headers and Kafka messages.\n\t* This ensures consistent traceability for each request.\n\n*\tHow it Works:\n\n\t* If a RequestId is not provided in the incoming request, one is automatically generated using UUID.\n\t* The RequestId is added to the logging context and HTTP response headers for reference.\n\t\n#### 3. MDC Propagation\n* Mapped Diagnostic Context (MDC) is used for adding contextual information (like RequestId) to logs dynamically.\n\n* MDC ensures that all logs within a given request are tagged with its unique RequestId, making it easy to filter and analyze logs.\n\n\n\n## Dependencies\n* **Spring Boot 3.4.1**\n* **Kafka** for messaging\n* **Lombok** for reducing boilerplate code\n* **Checkstyle** for code quality enforcement\n* **Springdoc** for API documentation\n\n## Configuration\n###  Rest Module\n#### `application.properties`\n* **Kafka Topics**:\n\t* ```kafka.result-topic=calculation-result-topic```\n\t* ```kafka.request-topic=calculation-request-topic```\n* **Kafka Servers**: ```spring.kafka.bootstrap-servers=broker:29092```\n* **Swagger API Path**: ```/swagger-ui.html```\n* **Server Port**: ```8081```.\n### MDC Configuration (MdcFilterConfig.java)\n* Generates and manages correlation IDs for tracking requests.\n\n## REST API Endpoints\n\n### Calculator Endpoints\n\n* **Addition**:\n`GET /api/calculator/sum?a={num1}\u0026b={num2}`\n* **Subtraction**:\n`GET /api/calculator/sub?a={num1}\u0026b={num2}`\n* **Multiplication**:\n`GET /api/calculator/multi?a={num1}\u0026b={num2}`\n* **Division**:\n`GET /api/calculator/div?a={num1}\u0026b={num2}`\n\n\n##### **Example**: \n```http://localhost:8081/api/calculator/sum?a=2.0\u0026b=7 ```\n##### **Response**: \n\n`\n{\n    \"result\": \"9.0\"\n} `\n\n## Kafka Messaging Flow\n\n#### Rest Module\n* **Producer**: Sends requests from the user to Kafka and forwards requests to the Calculator module.\n* **Consumer**: Listens for responses in the calculator module.\n\n#### Calculator Module\n* **Consumer**: Listens for requests in kafka from the rest module\n* **Producer**: Does the calculation and sends the response to the rest module\n\n## Extras\n\n### Continuous Integration and Testing with GitHub Actions\n* The project uses **GitHub Actions** to automate the build, test, and integration processes. The workflow file is defined in `.github/workflows/actions.yml`.\n*  Runs on pull requests targeting the main branch.\n\n#### Key Features\n1.  Automated Build:\n\n\t* Sets up Java 21 and Docker for the environment.\n\t* Builds the application using Docker Compose.\n\t* Does unit and integration testing inside modules\n\n2. Integration Testing:\n\n\t* A REST API endpoint (`/api/calculator/sum`) is tested to verify the application's functionality.\n\n3. Tear Down:\n\n\t* Ensures Docker containers are stopped and removed after the test, even if the workflow fails.\n  \n### Swagger API Documentation\n* The project includes Swagger/OpenAPI integration for exploring and testing the API.\n* After running the application, access Swagger UI at: http://localhost:8081/swagger-ui.html.\n\n![Alt Text](./images/swagger.png)\n\n\n### Code Quality and Documentation\n\n#### 1. Checkstyle\n* Checkstyle is used to enforce a consistent coding style and ensure code quality across the project.\n\n* The project uses a custom Checkstyle configuration based on the Google Checks standard with additional rules tailored for this project.\n\n* Configuration File:\n\n\t* The custom rules are defined in google_checks_custom.xml.\nFeatures of the Custom Checkstyle Configuration:\n\n#### 2. JAutodoc for JavaDocs\n* JAutodoc is used to automate the generation of JavaDoc comments for classes, methods, and fields.\n\n* Features:\n\n\t* Automatically generates JavaDoc stubs for missing documentation.\n\t* Encourages consistent and thorough documentation throughout the codebase\n\n### Angular Frontend\n* The Angular frontend provides a simple interface to interact with the calculator API.\n* Access the frontend at:\nhttp://localhost:4200.\n* It supports:\nAdding, subtracting, multiplying, and dividing numbers.\n* Displaying results dynamically.\n\n![Alt Text](./images/frontend.png)\n\n### Kafka UI\n* The project includes a Kafka UI tool for monitoring Kafka topics, messages, and consumer groups.\n* Access the Kafka UI at:\n http://localhost:8086.\n* Features of the Kafka UI:\n\t* View and manage Kafka topics.\n\t* Inspect consumer groups and their statuses.\n\t* View messages in real-time.\n\t\n![Alt Text](./images/kafkaUi.png)\n\n## Future Features\n\n\n#### 1. Enhanced API Features\n* **Authentication and Authorization**:\n\t* Integrate OAuth2, JWT, or API key-based authentication for secure API access.\n\t* Role-based access control (RBAC) to restrict certain operations.\n* **Advanced Calculator Operations:**\n\t* Add support for scientific calculations (e.g., trigonometry, logarithms, etc.).\n\t* History of calculations per user or session.\n\t* Support for batch calculations (e.g., an array of operations sent in a single request).\n\n\n#### 2. Frontend Enhancements\n* Enhanced UI/UX:\n\t* Add a responsive design with Bootstrap or Material Design.\n\n\n#### 3. Database Integration\n* Persistent Storage:\n\t* Store calculation history, user preferences, and logs in a database (e.g., MySQL, PostgreSQL, or MongoDB).\n\n#### 4. Performance and Scalability\n* Horizontal Scaling:\n\t* Add support for Kubernetes or AWS ECS to scale services dynamically.\n* Load Testing and Optimization:\n\t* Integrate tools like JMeter or Gatling to test the API under heavy loads.\n\t* Optimize Kafka message handling for higher throughput.\n\n#### 5. Observability and Monitoring\n* Logging and Monitoring:\n\t* Integrate Grafana and Prometheus.\n\t* Add structured logging with JSON format for easier parsing.\n* Distributed Tracing\n\t* Implement distributed tracing with tools like OpenTelemetry or Zipkin.\n* Health Checks:\n\t* Add endpoints for service health and readiness probes for better observability.\n\t\n#### 6. Security Improvements\n* Rate Limiting:\n\t* Prevent abuse by limiting the number of requests per user or IP address.\n* Data Validation:\n\t* Enhance input validation to prevent injection attacks or malformed data.\n\n* Add security\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluiscvillarreall%2Frestcalculator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluiscvillarreall%2Frestcalculator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluiscvillarreall%2Frestcalculator/lists"}