is-my-coffee-cold

A full-stack web application to calculate how long you have until your coffee goes cold.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

is-my-coffee-cold is a simple full-stack web application built to calculate the amount of time you have until your coffee goes cold, i.e., becomes undrinkable. The application achieves this through the combination of localised weather data sourced via external API calls alongside the Huen's method (otherwise referred to as the modified Euler method) for interpolating polynomials and Newton's law of cooling.

Essentially, the crux of this application is equating the point at which the temperature of a coffee, $t$, is less than the undrinkable threshold supplied, e.g., $t_{x} = 40$ degrees Celcius. The primary equation being that of Newton's law of cooling:

$$ T = Ce^{-kt} + T_{a} $$

To briefly summarise the mathematics utilised, in interpolation, we are generally given a set of $(x, y)$ coordinates. Given this, we can determin a function $f$ that passes between these two points. While, a second-order function, e.g., Taylor's method would provide higher accuracy than Huen's method; the requirement to differentiate $f(t, y)$ makes the gains in accuracy not entirely worth the loss in optimisation. As such, instead of differentiating $f(t, y)$ directly, we use a numerical approximation to the derivative.

Given a derivative of a function is the limiting value of the slope of the line connecting two points on a curve, then for suitably small values of step-size $h$, it is possible to use the following approximation.

$$ f'(t*{i}, y*{i}) \approx \frac{f(t*{i+1}, y*{i+1}) - f(t*{i}, y*{i})}{h}$$

Then using Euler’s method to approximate $y_{i+1}$ on the right-hand side (RHS) to second order locally we derive what is called the modified Euler method. The mathematical explanation of this can be seen here. Notably, this equation does not take into account the impacts of say being indoors compared to outdoors or the material the coffee cup is made of. Rather it assumes that the temperature of the coffee will change in direct proportion to the surrounding temperature in the area.

The remainder of the application follows standard paradigms for CRUD applications, albeit expanded to a full-stack pattern with a back-end API load-balanced via an API Gateway.

(back to top)

Built With

The following are the main languages and technologies utilised in building the application.

• 
• 
• 
• 
• 

(back to top)

Getting Started

To run the entire application locally you can follow either one of two options:

1. Using Docker
2. Manual execution

Prerequisites

The following are the assumed prerequisites required for local development and usage of the application.

• npm

  npm install npm@latest -g

• go
  • Follow the instructions here.
• docker
  • Follow the instructions here.

Installation

General

For both pathways in local development and usage of the application, you will need your own Firebase Admin SDK configuration. You can get one here. Once this has been completed:

1. Clone the repository

   git clone https://github.com/jamestkelly/is-my-coffe-cold.git

2. Copy the environment variables for each respective service

   cd api && cp .env.template .env && cd ../frontend && cp .env.template .env

3. Populate the environment variables for each service with the corresponding values.

Via Docker Compose

1. From the root of the repository:

   cd /path/to/is-my-coffee-cold
   docker compose up

Manual Execution

1. Install the required packages

   cd api
   go mod install
   
   cd ../frontend
   npm install

2. Initialise the back-end API server

   cd api
   go run cmd/server/main.go

3. Initialise the front-end

   cd frontend
   npm run start

(back to top)

Usage

Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.

For more examples, please refer to the Documentation

(back to top)

Roadmap

• Build original application (re: is-my-coffee-cold/v1)
• Create new design for the new brew, e.g., 2023 onwards.
• Build API microservice.
  • Convert original TypeScript code to Go for calculating coffee temperature decay.
  • Integrate Firebase Admin SDK.
  • Implement an authentication (auth) service.
• Abstract API microservices behind API Gateway.
• Build new front-end application.
  • Integrate with API microservice via API Gateway.
  • Integrate API microservices with front-end client application.
• Establish application life-cycle.
  • Create Docker images via corresponding Dockerfiles for local containerised development.
    • Front-end
    • API
  • Implement Kubernetes for application microservices.
    • API
    • API Gateway (Kong)
  • Implement build and deploy pipeline for the front-end via Firebase.
  • Implement build and deploy pipelines for the API and API Gateway to Oracle Cloud Infrastructure.
• Add sub-repository specific README.md information, e.g., for the API and front-end.
• Write up documentation covering application information and host it via GitHub repository Wiki.
• Push stable release of the application.
• Create long-term roadmap.
• Implement a way for users to provide feedback and bugs beyond GitHub issues.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the GNU Affero General Public License. See LICENSE.txt for more information.

(back to top)

Contact

Jim Tran kelly - [email protected]

Project Link: https://github.com/jamestkelly/is-my-coffee-cold

(back to top)

Acknowledgments

The following are several references and guides used in building the application that I would like to acknowledge.

• Best-README-Template

(back to top)