search

jamestkelly / is-my-coffee-cold

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.
GNU Affero General Public License v3.0
2 stars 0 forks source link
docker firebase golang kubernetes nextjs typescript

readme

Contributors Forks Stargazers Issues GNU License LinkedIn


Logo

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
  2. Getting Started
  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.

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

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 - jimkelly.t@outlook.com

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.

(back to top)