Why? What? Who? How?

# Why?

"Store locators" are a common use-case for most retailers or organisations with physical premises.
We have built them for a few of our clients and it's time to make a _generic_ example that _anyone_ can understand and learn from!

# What?

A tutorial showing how to build a "find my nearest `X`" (_AKA "store locator"_) using freely available location data, PostgreSQL, ETS and Elixir/Phoenix.

> Note: The end result should be a reasonably attractive browser application that allows the person to input a UK postcode and will display both their postcode location and the location of the `n` nearest `X` on a map with the list below the map showing the distance to the `X`.
Clicking on the link in the _list_ should open the default map application on the device or if it's a desktop/laptop should open Google Maps in full-screen using a `target="_blank"`.

# Who?

People who want to learn about Geolocation, Google Maps, Distance calculation and rapid lookups in medium-sized datasets.
Anyone who wants to learn how to build a real-world "store finder" in Elixir/Phoenix.

> Why is @RobStallion our _best_ person to write this example/tutorial?
> Simple: he has both the **professional experience** having worked for DPD couriers so he is _personally_ aware of the ["Travelling Salesman" problem](https://en.wikipedia.org/wiki/Travelling_salesman_problem) ...
Incidentally, DPD has a decent "Store Locator": https://www.dpd.co.uk/apps/shopfinder/index.jsp
Which has _much_ of the functionality this example will have.
I leave it to you to determine if the UX is the _best_ it can be. (_or if the UI is a bit "cluttered" ..._ 🤔)

# _How_?

@RobStallion please _estimate_ how long it will take you to convert the knowledge you gained while building the feature for our client: https://github.com/club-soda/club-soda-guide/pull/291 into a stand-alone example app that allows people to input their postcode and find the _nearest_ `X` (_where `X` is your choice of "vegan restaurant", "train station", "free outdoor gym" ... - or whatever data is publicly available, interesting to you and easy to parse..._ 😉)

# _Todo_

+ [ ] Start by _documenting_ the ***raison d’être*** of the repo (_expanding on what I have written above_)
our **Objective** with this example/tutorial is 4-fold:
+ [ ] 1. **_Clearly_ explain** to everyone in the CS team how the "**Venue Locator**" functionality works.
(_our **current** team might all understand the code because everyone read/reviewed the PR, but both **future** team members and the client's internal/external maintainers will not. so our objective is to have **comprehensive documentation** that answers all their questions **proactively**_)
+ [ ] 2. Create a **_generalised_ learning resource** that ***anyone*** in the community can use to ***understand*** the concepts and apply them _practically_:
+ [ ] What are Longitude and Latitude? (_give a micro history lesson to contextualise_)
+ [ ] What is Geolocation?
+ [ ] What is Geocoding? (_geo-encoding_)
+ [ ] What is _Reverse_ Geocoding?
+ [ ] The Example app should Ask people for access to their location in the browser.
https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API
+ [ ] 3. ***Demonstrate*** the benefits Phoenix/Elixir and it's "free" in-memory Database **ETS** which allows for the **fastest _possible_** lookups; even faster than XYZ programming language **`Redis`**!
+ [ ] Our objective is to make the "_find nearest `X`_" as ***fast*** as it _can_ be to _demonstrate_ that Phoenix/Elixir is the [**_logical_ choice**](https://github.com/dwyl/learn-elixir/issues/102) that _all_ websites should be built with. Once the Heroku app boots, the response time for a lookup should be _sub_ 200ms. 🏎
+ [ ] Load the Google Maps JS library in the footer of the home page so that pins will appear fast.
+ [ ] Show **_one_ result** for the "nearest `X`" as _text_.
then display the map, then the _list_ of nearest `X`'s ...
i.e. create a "content hierarchy" based on _relevance_ to the user.
+ [ ] 4. **_Practice_ Technical Writing Skills**. Writing is the _single_ best way to practice your _thinking_ skills. Communicating your knowledge/understanding of a topic with others is the difference between a _beginner_ and a _senior_ engineer. It's the reason all universities require students to _teach_ before they can "level up". The more _teaching_ you do the better you will _understand_ the topic and _forcing_ yourself to _explain_ the material to a _complete_ beginner means you have to understand it at a _much_ deeper level.

> **Note**: once the UK postcode "find nearest X" example is working, if you want to take this to it's "logical conclusion" and go _global_, open an issue to _expand_ the tutorial to allow people to type in _any_ address and use Google's/GeoNames geocoding API to find the Lat/Long and then lookup the nearest Airport (_this gloabal data is freely available: https://openflights.org/data.html ..._) the _reason_ we aren't doing the _global_ version _first_ is that this example's _first_ objective is to serve as **_comprehensive_ documentation** for the CS functionality.

+ [ ] You, the _creator_ of this example/tutorial, are free to use your creativity/imagination for coming up with the UX/UI, but you should include _examples_ of the best implementations on _existing_ websites.
i.e. go looking for [_real world examples_](https://github.com/dwyl/cid#real-world-examples) of best and _worst_ Store Locators for UK-based websites/services and _list_ them in the "Appendix" of the example, similar to how you wrote the "YouTube" example in: https://github.com/dwyl/cid/pull/12
+ [ ] If you get "stuck" [***ask questions***](https://github.com/nelsonic/nelsonic.github.io/issues/616)!