dwyl / dwyl/phoenix-ecto-append-only-log-example
Basic Address Book Example/Explanation
- Dominant language
- Elixir
- Stars
- 82
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
At present this tutorial does a _good_ job of diving straight into the `code` example. ✅
We feel that _explaining_ the context of the example would help people understand it.
_Most_ basic address books, like the one you have on your mobile phone, do not preserve history. This makes sense because most people only _want_ the latest (_up-to-date_) version of a person's address.
But using our imagination for a bit we can _easily_ demonstrate that having _history_ in addresses can be _highly_ useful.
# Intro
In a "normal" Phoenix App, when a schema is generated using `phx.gen` ("generator") command e.g:
```
mix phx.gen.schema Address addresses name:string address_line_1:string
address_line_2:string city:string postcode:string tel:string
```
or
```
mix phx.gen.html Accounts Address addresses name:string address_line_1:string
address_line_2:string city:string postcode:string tel:string
```
A standard PostgreSQL Table called **`addresses`** is created with the following schema:

A standard PostgreSQL Table does not store the _history_ of a record so when the record/row gets updated, we have no way of "undoing" the update. Let's consider a _basic_ example.
# _Basic_ Example
We have a basic Address Book app for storing the addresses of our friends & family.
If we insert a record into the **`addresses`** table (see https://github.com/dwyl/phoenix-ecto-append-only-log-example/issues/17#issuecomment-486610753) we get the following row:
id| name | address_line_1 | address_line_2 | city | postcode | tel | inserted_at |
--|-----------|--------------|--------------|-----------|--------|---------|-------------------|
1 | Thor | The Hall | Valhalla | Asgard | AS1 3DG | 123123 | 2019-04-25 10:01:42 |
This is _very_ much "traditional CRUD" approach; the primary key (_unique identifier_) of the record is **`1`** and if we were to _update_ this record, it would ***overwrite*** the previous version (_and any history would be lost_).
id| name | address_line_1 | address_line_2 | city | postcode | tel | inserted_at | updated_at
--|-----------|--------------|--------------|-----------|--------|---------|--------|--------|
1 | Thor | 177A Bleecker Street | c/o Dr. Strange | New York | NY 10012 | 98765 | 2019-03-14 10:01:42 | 2019-04-17 01:03:13|
In our scenario above, we start out with our friend [Thor](https://youtu.be/kLyGicjc6_M?t=38)'s "home" address in Asgard.
Thor moves to Earth and is _temporarily_ staying with his buddy Dr. Strange in New York.
After completing finishing his "job" on Earth, Thor moves back to Asgard to take a break from the chaos of NY. Thor _forgets_ to leave his [forwarding address](https://en.wikipedia.org/wiki/Mail_forwarding) assuming that everyone just _knows_ where to send him mail.
Sadly, because we lost Thor's previous address when we updated the record, we have no idea how to contact him. Without record history, we lose contact with our friends. 😞
> **Note**: I have attempted to give this example in https://github.com/dwyl/phoenix-ecto-append-only-log-example/issues/5#issuecomment-425686791 but it appears to have been _lost_ in that thread. My intention is to include this example in the "What?" section of the main `README.md` to help people _understand_ the benefit of immutable data with a _simple_ example.
# _Real World_ Example
If you have ever used an E-commerce shopping website, most of them allow you to have _multiple_ addresses which are effectively an address "history".

When you _update_ your address on Amazon, you are actually inserting a **new _version_** of you address. The way you can _check_ this is that your _previous_ orders that went to the _previous_ address have not been altered.
As an end-user you have no visibility of the underlying data structure, but the reality is that _all_ changes to your address are carefully recorded by Amazon to ensure full accountability and prevent fraud.
If a criminal was to gain access to your Amazon account, add their own address, send parcels to themself and then attempt to delete their address, it's not going to help them, their address is very much recorded in the account history and will be passed to the fraud investigation team.
Try it yourself, temporarily change your address to your Work or a Friend's address send an order to them. Then **`delete`** the address and go "Order Reports", the address is still there.

You might not _think_ about address history as a "consumer", but if your account was ever hacked, you would be very grateful for the history.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the main README.md and locate the “What?” section referenced in the issue. Review the existing tutorial flow and the address-book explanation in this issue, then add context showing the difference between traditional CRUD updates and immutable address history. Done means the README explains the example clearly before directing readers into the code.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- elixir, postgresql
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100