Cupprum / GreenMoStalker

Notify me about GreenMobility cars which can be put on charger.

Greenmobility Stalker

Project Description:

This project aims to create an API that serves as a proxy to the functionality provided by Greenmobility. When a Greenmobility car is placed on a charger while low on battery, users receive free driving minutes. The purpose of this API is to allow for easier automation of fetching information about cars in order to get free minutes.

Diagram:

Parts of project:

The project is deployed on AWS using the AWS CDK for Typescript. The user interacts with an API Gateway protected by a Usage Plan that requires an API token for authentication. Once authenticated, the API Gateway triggers a Lambda function. The Lambda function, written in Typescript, determines the location to query, executes the request against the Greenmobility API, filters the cars that can be charged, finds available chargers in proximity from Spirii API, and generates a static image using the Geoapify Static Maps API. The image is returned as the response body from the Lambda function. Sensitive information is stored securely in the SSM Parameter Store. The API is documented using OpenAPI. The project is deployed by executing a Dagger pipeline, which is also written in Typescript. The project is automatically deployed with Github Actions.

Calling the API from Various Devices:

The API Gateway can be accessed from different devices, including iPhones using the Shortcuts app. Apple Shortcuts provide powerful automation capabilities, such as detecting when a user is returning home and triggering the query against the API to fetch locations of available cars to charge in the surrounding area. Additionally, Shortcuts allow for creation of simple cronjobs (automatically trigger the request at specific time), that can be configured to only execute the request when the user is in the desired location location.

Development:

It is recommended to work on this project from a Github Codespaces with a predefined custom Fedora container.

Configuration:

The project requires the following env vars.

export GREENMO_AWS_ACCOUNT='xxx'  # AWS account into which the project is deployed.
export GREENMO_AWS_REGION='xxx'  # Preferred AWS Region.
export GREENMO_AWS_ACCESS_KEY_ID='xxx'  # MachineAccount credentials used during deployment.
export GREENMO_AWS_SECRET_ACCESS_KEY='xxx'  # MachineAccount credentials used during deployment.
export GREENMO_OPEN_MAPS_API_TOKEN='xxx'  # Token used to authenticate against [Geoapify](https://www.geoapify.com).
export GREENMO_API_KEY='xxx'  # Authentication key used against the API Gateway.

Logic:

The logic is located in logic/chargableCars.

Installation:

cd logic/chargableCars
npm ci # Because npm install overwrites the package-lock.json file.

Execute tests:

npm test

Local development: The entrypoint for the code is located in logic/chargableCars/lib/index.ts. The commented code at the bottom of the file is used for local development.

Infra:

The infra is located in the following folder cdk.

Installation:

cd cdk
npm ci # Because npm install overwrites the package-lock.json file.

Execute tests:

npm test

Deployment pipeline:

Dagger is used for the deployment purposes. By default the pipeline is executed from github actions, but it can also be executed locally and triggered manually. The pipeline is located in ci.

Installation:

cd ci
npm ci # Because npm install overwrites the package-lock.json file.

Execute:

npm run dagger

OpenAPI 3 Documentation:

The openapi.json specification of the project can be updated from the state of currently deployed API Gateway. Command aws apigateway get-export --parameters extensions='integrations' --rest-api-id 'xxxxxx' --stage-name 'prod' --export-type 'oas30' 'new-openapi.json' --region 'eu-central-1'" can be used to fetch the current configuration. However it contain also some definitions about APIGateway integration, which are not that interesting to me. The api supports CORS for https://editor.swagger.io/ origin, so the api can be tested from the official documentation from the Browser.

Version 1:

The first iteration of this project utilizes a cronjob running on GCP and is deployed using Terraform. A Cloud Scheduler triggeres a Cloud Function (version 2) which queries the Greenmobility API for cars at a specific location. The function filteres the cars with low battery and generates a map using the Google Static Maps API. The map displays locations where cars could be charged for free minutes. The generated image is then send to the Pushover application and displayed on my phone. Sensitive information, such as tokens, are stored securely in Secret Manager.

Reasoning:

Several factors influenced my decision to make certain changes in the project:

1. Moving away from GCP: I chose to shift away from GCP due to concerns regarding their billing practices and the lack of transparency in understanding the charges associated with specific resources. Additionally, GCP lacks a comparable tool to AWS CDK, which I found preferable for handling deployments. The AWS CDK's ability to write infrastructure using a programming language allows for faster iterations and, in my opinion, improves code readability, especially on shorter projects.

2. Transition from Terraform to AWS CDK: I made the decision to switch from Terraform to AWS CDK because I find writing infrastructure in a programming language more intuitive, especially on smaller projects. This change allows for faster iterations and simplifies the development process.

3. Choice of storing secrets: Instead of utilizing Secrets Manager to store secrets, I opted for using SSM Parameter Store. This decision was driven by cost considerations, as SSM Parameter Store is less expensive than Secrets Manager. Additionally, since the secrets I'm dealing with don't require the extra protection provided by Secrets Manager, I found Parameter Store to be a suitable and more cost-effective alternative.

4. Switching to Geoapify Static Maps API: I transitioned from using Google Maps Static API to Geoapify Static Maps API due to the requirements imposed by Google. The Google API necessitates attaching a credit card to the account, while Geoapify offers a free tier without the need for credit card details. Moreover, I appreciate that Geoapify utilizes the OpenStreetMap infrastructure, which adds to its appeal.