{"id":26537349,"url":"https://github.com/rcsoyer/telemetry-service","last_synced_at":"2026-04-11T03:08:14.056Z","repository":{"id":282854338,"uuid":"944613160","full_name":"rcsoyer/telemetry-service","owner":"rcsoyer","description":"Manages telemetry data from multiple entry points","archived":false,"fork":false,"pushed_at":"2025-03-24T13:31:05.000Z","size":337,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T14:31:50.107Z","etag":null,"topics":["docker","gradle","hibernate","java-21","kafka","lombok","mapstruct","postgresql","spring-boot","spring-data-jpa","spring-events","spring-security-jwt","swagger3","virtual-threads"],"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/rcsoyer.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-03-07T16:53:35.000Z","updated_at":"2025-03-24T13:31:08.000Z","dependencies_parsed_at":"2025-03-24T14:27:38.564Z","dependency_job_id":null,"html_url":"https://github.com/rcsoyer/telemetry-service","commit_stats":null,"previous_names":["rcsoyer/telemetry-service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rcsoyer/telemetry-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcsoyer%2Ftelemetry-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcsoyer%2Ftelemetry-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcsoyer%2Ftelemetry-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcsoyer%2Ftelemetry-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rcsoyer","download_url":"https://codeload.github.com/rcsoyer/telemetry-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcsoyer%2Ftelemetry-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004821,"owners_count":26083784,"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-10-10T02:00:06.843Z","response_time":62,"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":["docker","gradle","hibernate","java-21","kafka","lombok","mapstruct","postgresql","spring-boot","spring-data-jpa","spring-events","spring-security-jwt","swagger3","virtual-threads"],"created_at":"2025-03-21T22:29:40.566Z","updated_at":"2025-10-10T17:39:19.705Z","avatar_url":"https://github.com/rcsoyer.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# telemetry-service\nManages telemetry data from multiple entry points\n\n### Process IoT devices data\nConsume Kafka topics to process data in scalable way.\nThe message events in the topics are telemetry data published by IoT devices.\n\n### The application provides REST APIs for users to: \n- register accounts;\n- login and obtain a JWT to access other resources; \n- register IoT Devices;\n- view summary data about the registered IoT devices;\n\nThe resources are secured with JWT, Bearer Token, authentication.\n\n## Setup local development environment\n\nThe minimum requirements to run the application are:\n\n- ``Java 21``\n    - any ``JDK 21`` distro should work: Eclipse Temurin, OpenJDK, Oracle JDK...etc\n- ``Docker engine``\n    - the integration tests need a Docker engine to run `Postgres` and `Kafka` on containers;\n    - `Docker Desktop` is an easy way to get Docker on your OS;\n        - https://docs.docker.com/desktop/\n- If you run the application through an `IDE`, such as `IntelliJ IDEA`, you may need to enable\n  annotation processing to support `Lombok` and `MapStruct`.\n\n\n## Building the application\n\nThe application can be built via gradle on your IDE.\n\nOr you can build the application via the command line in terminal:\n\n````./gradlew clean build````\n\n### CI/CD pipeline\nThis project uses GitHub Actions for CI/CD pipeline: [gradle build](.github/workflows/gradle.yml).\n\nThe pipeline is triggered on every push to the `master` branch.\n\nThe pipeline runs the following steps:\n- Git checkout the code\n- Setup Java 21\n- Build the application\n    - Run the unit tests\n    - Run the integration tests\n\n## Running the application\n\nThe project provides an easy to use ``dev`` Spring profile:\n[application-dev.yml](src/main/resources/application-dev.yml).\n\nFrom that file, you can adjust the connection to local Postgres and Kafka instances.\n\nOr you may simply run a Postgres and Kafka on a Docker container with the expected url configuration\nand credentials described in the file.\n\n### Docker compose\n- Run the docker compose file, in the /dev folder of this project,\n  to create the `Postgres` and `Kafka`  containers needed to run the application\n  on Spring's dev profile.\n\nThe application then can be run in two ways:\n\n- through the IDE\n    - IDEs via auto-detection of the main class with the Spring profile: dev\n- through the command line\n    - ```./gradlew bootRun --args='--spring.profiles.active=dev'```\n\n### Step by step usage\n1. Import the postman collection located in the /dev folder of the project;\n2. Create an Account with: http://localhost:8080/swagger-ui/index.html#/account-controller/register;\n2. Login with that Account via browser or via REST API (check the options under the \"Featues\");\n3. With a JWT at hand, now IoT Devices can be registered: http://localhost:8080/swagger-ui/index.html#/io-t-device-controller/register;\n4. After registering a device Kafka events can be published with a registered deviceId(the app generated UUID);\n5. Use the APIs of different IoT Devices to view the summary data using the source deviceId\n\n#### Publish to Kafka topics\nThe Kafka Topics are created automatically when the application runs.\nIn order to publish events to the topics it's needed a Kafka client.\n\nOn IntelliJ IDEA, it's possible to use the Big Data Tools to connect to a Message broker.\nIn this case the local Kafka Broker from which get a Producer and publish events to the topics.\nTo configure the Kafka Broker set the following in the Big Data Tools:\n- Enable connection: check the box\n- Bootstrap servers: 127.0.0.1:9092\n- Authentication: none\n\n\nThere are 3 topics, one for each supported IoT Device type:\n1. fridgeEvents\nIn the Kafka client producer specify for this topic:\n- value - type json:\n```json\n{\n  \"deviceId\" : \"UUID\" //the UUID of a registered IoTDevice\n  \"temperature\" : double //a numeric double value with the temperature\n}\n```\n\n2. coffeeMachineEvents\n   In the Kafka client producer specify for this topic:\n- value - type json:\n```json\n{\n  \"deviceId\" : \"UUID\" //the UUID of a registered IoTDevice\n  \"status\" : \"READY | ERROR | IN_PROGRESS | IDLE\" //an enum definition with allowed event values\n}\n```\n\n3. thermostatEvents\n      In the Kafka client producer specify for this topic:\n- value - type json:\n```json\n{\n  \"deviceId\" : \"UUID\" //the UUID of a registered IoTDevice\n  \"temperature\" : double //a numeric double value with the temperature\n  \"humidity\" : double //a numeric double value with the humidity\n}\n```\n\n\n## API Testing\nA postman collection is available in the project dev directory:\n[telemetry-service postman collection](dev/Telemetry-Service-API.postman_collection.json).\n\nThis collection can simply be imported into Postman and used to test the API features exposed by\nthe application.\n\n## Features\n\n### Security\nUnless specified, all the endpoints require authentication to access.\n\nIf the client is not authenticated the application may redirect the client to the `login` page.\n\n### OpenAPI documentation\n\nThe application provides an OpenAPI documentation for better integration with other services.\n\n- The `Swagger UI` can be accessed via:\n    - http://localhost:8080/swagger-ui.html\n- The `OpenAPI` `yaml` can be downloaded via:\n    - http://localhost:8080/v3/api-docs.yaml\n\n### Manage Accounts\n\n- **Register** - ````POST /accounts````\n    - http://localhost:8080/swagger-ui/index.html#/account-controller/register\n    - Create a new client's Account in the platform\n    - Only legal age clients are allowed to register;\n    - The username must be unique;\n    - Upon successful registration, a default random secure password is generated and returned to\n      the user;\n    - No authentication is required to register;\n- Login\n    - ```GET /login```\n        - via browser its possible to access the login UI page: http://localhost:8080/login\n        - this is the ``formLogin`` feature automatically provided by Spring Security;\n        - upon successful login, the user receives their `JWT` that allows them to access protected\n          resources that they own;\n        - *Reference*: https://docs.spring.io/spring-security/reference/servlet/authentication/passwords/form.html\n    - ````POST /login````\n        - http://localhost:8080/swagger-ui/index.html#/login-endpoint/post_login\n        - Existing clients can login with their username and password;\n        - A `JWT` is generated upon successfully authenticated client;\n        - This endpoint is generated automatically by Spring Security and connects to a custom\n          success handler that generates the `JWT`;\n        - This is the same endpoint used by the `formLogin` feature;\n- Account Overview listing - ````GET /accounts````\n    - http://localhost:8080/swagger-ui/index.html#/account-controller/getAccountOverview\n    - List all the client's Bank Accounts;\n    - This is a secured endpoint that requires a valid `JWT` for access;\n    - If a valid `JWT` is provided, the client's banking details associated with the token are\n      fetched and returned;\n\n### Actuator\n\nThe application provides the Spring Boot Actuator endpoints for monitoring and management.\n\n- info ```GET /info```\n    - http://localhost:8080/swagger-ui/index.html#/Actuator/info\n    - Provides general information about the running application;\n    - http://localhost:8080/info\n    - Provides general information about the application;\n    - No authentication is required;\n- health ```GET /health```\n    - http://localhost:8080/swagger-ui/index.html#/Actuator/health\n    - Provides metrics about the health of the application;\n    - No authentication is required;\n- liveness ```GET /health/liveness```\n    - http://localhost:8080/health/liveness\n    - No authentication is required;\n- readiness ```GET /health/readiness```\n    - http://localhost:8080/health/readiness\n    - Provides metrics about the readiness of the application;\n    - No authentication is required;","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcsoyer%2Ftelemetry-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frcsoyer%2Ftelemetry-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcsoyer%2Ftelemetry-service/lists"}