From bc9739d4d3e51dc1eee369d20271fb2b693115a4 Mon Sep 17 00:00:00 2001
From: Paul Oliver <contact@pauloliver.dev>
Date: Thu, 29 Feb 2024 03:01:41 +0100
Subject: Added README

---
 README.md        | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 server/server.py |  5 +++++
 2 files changed, 52 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0306e82
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+# Timezone clock Vue component and Flask server
+
+
+## Flask server setup and launch
+After downloading this repo, navigate to `/server` directory to install python dependencies. Run the following commands
+to create a virtual env (assuming you have `virtualenv` and `pip` installed on your system):
+```console
+virtualenv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+To run the dev server, launch Flask as such:
+```console
+FLASK_APP=server.py FLASK_DEBUG=1 flask run
+```
+
+Server should now be running at `localhost:5000`. If you configure Flask to run on a different host/port, make sure to
+update the client config file accordingly (see below).
+
+
+## Vue client setup and launch
+On a different terminal, navigate into the `/client` directory. A basic Vue project is already setup. Assuming `npm` is
+installed on your system, you may run `npm install` to fetch all needed packages.
+
+Once that's done, launch the server by running `npm run serve`. You can open the client on your browser by navigating
+to `localhost:8080`.
+
+> Note: The client will access the Flask API via the url located in `/client/config/index.js`. So make sure to update
+> this file if you launch Flask on a different host/port.
+
+
+## Rationale
+I've included two endpoints on `server/server.py`. First one (`/zones`) serves a list of available timezones as
+outputted by `pytz.common_timezones`. Second endpoint (`/time-at/<path:zone>`) expects a single parameter, which
+*should* be an element of the previous list (otherwise a `404` is returned). Note I take advantage of the fact that
+`common_timezones` have a path-like syntax (e.g. `America/Argentina/Buenos_Aires`) by using the `path:` prefix on the
+decorator.
+
+A basic Vue project was set up with vue-cli. The important part is the `ZonePicker` component located in
+`/client/src/components/ZonePicker.vue`. After mount, the component fetches a list of timezones, and populates a
+`select` element with the returned zones. After the user selects a timezone, the `Get time` button becomes enabled and
+we can fetch the current time at that zone.
+
+Form inputs are also disabled while fetching the zones list (right after mount) and while waiting for a requested time
+(after clicking the button) so that only one request can be done at a time. We can uncomment the `time.sleep()`
+statements on the endpoint methods to simulate slow connection speeds, making this effect more noticeable.
diff --git a/server/server.py b/server/server.py
index f1ddaa9..ca28d51 100644
--- a/server/server.py
+++ b/server/server.py
@@ -1,3 +1,5 @@
+import time
+
 from datetime import datetime
 from flask import abort, Flask, jsonify
 from flask_cors import CORS
@@ -11,12 +13,15 @@ CORS(app)
 @app.route('/zones/', methods=['GET'])
 def zones():
     """ Return a list of common timezones """
+    # time.sleep(5) # Simulate slow connection
     return jsonify(common_timezones)
 
 
 @app.route('/time-at/<path:zone>', methods=['GET'])
 def time_at(zone):
     """ Return current time at given timezone """
+    # time.sleep(5) # Simulate slow connection
+
     if zone not in common_timezones:
         abort(404)
 
-- 
cgit v1.2.1