lagom · TimMoore · Mar 8, 2017 · Feb 24, 2017 · TimMoore · Mar 8, 2017
diff --git a/README.md b/README.md
@@ -1,135 +1,57 @@
-# Auction system
+[<img src="docs/logo.png" alt="Lagom" width="50%">](https://github.com/lagom/lagom)
 
-System architecture:
+[![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/lagom/lagom?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [<img src="https://img.shields.io/travis/lagom/lagom.svg"/>](https://travis-ci.org/lagom/lagom)
 
-# Item service
+# INTRO
+Lagom is a Swedish word meaning just right, sufficient. Microservices are about creating services that are just the right size, that is, they have just the right level of functionality and isolation to be able to adequately implement a scalable and resilient system.
 
-Manages the description and auction status (created, auction, completed, cancelled) of an item.
+Lagom focuses on ensuring that your application realises the full potential of the [Reactive Manifesto](http://reactivemanifesto.org/), while delivering a high productivity development environment, and seamless production deployment experience.
 
-## Queries handled
+This is a sample Scala auction site using the Lagom Framework. A [java version](https://github.com/lagom/online-auction-java) of the auction site is also available.
 
-* **getItem** - Gets an item by an ID.
-* **getItemsForUser** - Gets a list of items in a provided status that are owned by a given user.
+## Getting started
+To get started make sure you have sbt and git installed on your system. You will also need an active internet connection.
 
-## Events emitted
+### Running: Prerequisites
 
-* **AuctionStarted** (public) - When the auction is started, in response to **startAuction**.
-* **ItemUpdated** (private) - When user editable fields on an item are updated in response to **createItem**.
-* **AuctionCancelled** (private) - When the auction is cancelled, in response to **cancelAuction**.
-* **AuctionFinished** (private) - When the auction is finished, in response to **BiddingFinished**.
+- You will need to download and run an Elastisearch server:
 
-Event emitted publically are published via a broker topic named `item-ItemEvent`.
+```
+curl -L -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-5.0.2.tar.gz
+tar -xvf elasticsearch-5.0.2.tar.gz
+cd elasticsearch-5.0.2/bin
+./elasticsearch
+```
+### Running
 
-## Commands handled
+On another terminal, clone this repo and run the sample app using the command `sbt runAll`:
 
-### External (user)
+```
+git clone git@github.com:lagom/online-auction-scala.git
+cd online-auction-scala
+sbt runAll
+```
 
-* **createItem** - Creates an item - emits **ItemUpdated**.
-* **updateItem** - Updates user editable properties of an item, if allowed in the current state (eg, currency can't be updated after auction is started), emits **ItemUpdated**.
-* **startAuction** - Starts the auction if current state allows it, emits **AuctionStarted**.
-* **cancelAuction** (not supported) - Cancels the auction if current state allows it, emits **AuctionCancelled**.
+# Auction system - System architecture
 
-## Events consumed
+The auction system is the sum of 5 micro-services and a web gateway:
 
-### Bidding service
+* **[Item Service](docs/item-service.md)**: Manages the description and auction status (created, auction, completed, cancelled) of an item.
+* **[Bidding service](docs/bidding-service.md)**: Manages bids on items.
+* **[Search service](docs/search-service.md)**: Handles all item searching.
+* **[Transaction service](docs/transaction-service.md)**: Handles the transaction of negotiating delivery info and making payment of an item that has completed an auction.
+* **[User service](docs/user-service.md)**: a convenience service to stub user management. Don't use any code in `user-service` as reference on how to create a secure user management micro-service.
+* **web-gateway**: a [Play](https://www.playframework.com/) application providing web UI and acting as gateway to all previously described services.
 
-* **BidPlaced** - Updates the current price of the item.
-* **BiddingFinished** - Completes the auction if current state allows, emits **AuctionFinished**.
+Check the docs for each service for details on the **commands** and **queries** it serves as well as events the service **emits** and events it **consumes** from the [Message Broker](http://www.lagomframework.com/documentation/1.3.x/scala/MessageBrokerApi.html#Message-Broker-Support).
 
-# Bidding service
+## Good to know
 
-Manages bids on items.
+- Hello World Gitter8 seed
 
-## Queries handled
+For a simple, gentler, introduction to Lagom, have a look at the [Hello World gitter8 seed project](http://www.lagomframework.com/documentation/1.3.x/scala/GettingStarted.html) in the docs.
 
-* **getBids** - Gets all the bids for an item.
+- Getting help
 
-## Events emitted
+If you have any troubles and need help, feel free to ask in the [Gitter channel](https://gitter.im/lagom/lagom)
 
-* **BidPlaced** - When a bid is placed, in response to **placeBid**.
-* **BiddingFinished** - When bidding has finished, in response to **finishBidding**.
-
-## Commands handled
-
-### External (user)
-
-* **placeBid** - Places a bid, if the bid is greater than the current bid, emits **BidPlaced**.
-
-### Internal
-
-* **finishBidding** - Triggered by scheduled task that polls a read side view of auctions to finish, emits **BiddingFinished**
-
-## Events consumed
-
-### Item service
-
-* **AuctionStarted** - Creates a new auction for the item
-* **AuctionCancelled** - Completes an auction prematurely
-
-# Search service
-
-Handles all item searching.
-
-## Queries handled
-
-* **search** - Search for items currently under auction matching a given criteria.
-* **getUserAuctions** - Gets a list of all current auctions that a user is participating in by user ID.
-
-## Events consumed
-
-### Item service
-
-* **ItemUpdated** - Creates or updates the details for an item in the search index
-* **AuctionStarted** - Updates the status for an item to started
-* **AuctionFinished** - Deletes an item from the search index
-* **AuctionCancelled** - Deletes an item from the search index
-
-### Bidding service
-
-* **BidPlaced** - Updates the current price for an item, if it exists in the index
-
-# Transaction service
-
-Handles the transaction of negotiating delivery info and making payment of an item that has completed an auction.
-
-## Queries handled
-
-* **getTransaction** - Gets a transaction by an items ID.
-* **getTransactionsForUser** - Gets a list of all transactions that a given user is involved with.
-
-## Events emitted
-
-* **DeliveryByNegotiation** - When the buyer has selected by negotiation, in response to **submitDeliveryDetails**.
-* **DeliveryPriceUpdated** - When the seller has updated the delivery price, in response to **setDeliveryPrice**.
-* **PaymentDetailsSubmitted** - When payment details are submitted, in response to **submitPaymentDetails**.
-* **PaymentConfirmed** - When payment has been confirmed, in response to payment service **ReceivedPayment**.
-* **PaymentFailed** - When payment has failed, in response to payment service **FailedPayment**.
-* **ItemDispatched** - When the item has been dispatched, in response to **dispatchItem**.
-* **ItemReceived** - When the item has been received, in response to **receiveItem**.
-* **MessageSent** - When a user has sent a message, in response to **sendMessage**.
-* **RefundInitiated** - When the seller has initiated a refund, in response to **initiateRefund**.
-* **RefundConfirmed** - When a refund has been confirmed.
-
-## Commands handled
-
-### External (user)
-
-* **sendMessage** - Send a message to the other user, emits **MessageSent**.
-* **submitDeliveryDetails** - Used by the buyer to submit delivery details, emits **DeliveryDetailsSubmitted**.
-* **setDeliveryPrice** - Used by the seller to set the delivery price when delivery option is by negotiation, emits **DeliveryPriceUpdated**.
-* **submitPaymentDetails** - Used by the buyer to submit payment details.
-* **dispatchItem** - Used by the seller to say they have dispatched the item.
-* **receiveItem** - Used by the buyer to say they have received the item.
-* **initiateRefund** - Used by the seller to initiate a refund.
-
-## Events consumed
-
-### Item service
-
-* **AuctionFinished** - Creates the transaction.
-
-### Payment service
-
-* **ReceivedPayment** - Indicates the payment has been made, emits **PaymentConfirmed**.
-* **FailedPayment** - Indicates payment failed, emits **PaymentFailed**.
-* **MadeRefund** - Indicates a refund was made, emits **RefundConfirmed**.
diff --git a/docs/bidding-service.md b/docs/bidding-service.md
@@ -0,0 +1,31 @@
+
+# Bidding service
+
+Manages bids on items.
+
+## Queries handled
+
+* **getBids** - Gets all the bids for an item.
+
+## Events emitted
+
+* **BidPlaced** - When a bid is placed, in response to **placeBid**.
+* **BiddingFinished** - When bidding has finished, in response to **finishBidding**.
+
+## Commands handled
+
+### External (user)
+
+* **placeBid** - Places a bid, if the bid is greater than the current bid, emits **BidPlaced**.
+
+### Internal
+
+* **finishBidding** - Triggered by scheduled task that polls a read side view of auctions to finish, emits **BiddingFinished**
+
+## Events consumed
+
+### Item service
+
+* **AuctionStarted** - Creates a new auction for the item
+* **AuctionCancelled** - Completes an auction prematurely
+
diff --git a/docs/item-service.md b/docs/item-service.md
@@ -0,0 +1,35 @@
+# Item service
+
+Manages the description and auction status (created, auction, completed, cancelled) of an item.
+
+## Queries handled
+
+* **getItem** - Gets an item by an ID.
+* **getItemsForUser** - Gets a list of items in a provided status that are owned by a given user.
+
+## Events emitted
+
+* **AuctionStarted** (public) - When the auction is started, in response to **startAuction**.
+* **ItemUpdated** (private) - When user editable fields on an item are updated in response to **createItem**.
+* **AuctionCancelled** (private) - When the auction is cancelled, in response to **cancelAuction**.
+* **AuctionFinished** (private) - When the auction is finished, in response to **BiddingFinished**.
+
+Event emitted publically are published via a broker topic named `item-ItemEvent`.
+
+## Commands handled
+
+### External (user)
+
+* **createItem** - Creates an item - emits **ItemUpdated**.
+* **updateItem** - Updates user editable properties of an item, if allowed in the current state (eg, currency can't be updated after auction is started), emits **ItemUpdated**.
+* **startAuction** - Starts the auction if current state allows it, emits **AuctionStarted**.
+* **cancelAuction** (not supported) - Cancels the auction if current state allows it, emits **AuctionCancelled**.
+
+## Events consumed
+
+### Bidding service
+
+* **BidPlaced** - Updates the current price of the item.
+* **BiddingFinished** - Completes the auction if current state allows, emits **AuctionFinished**.
+
+
diff --git a/docs/logo.png b/docs/logo.png
diff --git a/docs/search-service.md b/docs/search-service.md
@@ -0,0 +1,23 @@
+# Search service
+
+Handles all item searching.
+
+## Queries handled
+
+* **search** - Search for items currently under auction matching a given criteria.
+* **getUserAuctions** - Gets a list of all current auctions that a user is participating in by user ID.
+
+## Events consumed
+
+### Item service
+
+* **ItemUpdated** - Creates or updates the details for an item in the search index
+* **AuctionStarted** - Updates the status for an item to started
+* **AuctionFinished** - Deletes an item from the search index
+* **AuctionCancelled** - Deletes an item from the search index
+
+### Bidding service
+
+* **BidPlaced** - Updates the current price for an item, if it exists in the index
+
+
diff --git a/docs/transaction-service.md b/docs/transaction-service.md
@@ -0,0 +1,46 @@
+# Transaction service
+
+Handles the transaction of negotiating delivery info and making payment of an item that has completed an auction.
+
+## Queries handled
+
+* **getTransaction** - Gets a transaction by an items ID.
+* **getTransactionsForUser** - Gets a list of all transactions that a given user is involved with.
+
+## Events emitted
+
+* **DeliveryByNegotiation** - When the buyer has selected by negotiation, in response to **submitDeliveryDetails**.
+* **DeliveryPriceUpdated** - When the seller has updated the delivery price, in response to **setDeliveryPrice**.
+* **PaymentDetailsSubmitted** - When payment details are submitted, in response to **submitPaymentDetails**.
+* **PaymentConfirmed** - When payment has been confirmed, in response to payment service **ReceivedPayment**.
+* **PaymentFailed** - When payment has failed, in response to payment service **FailedPayment**.
+* **ItemDispatched** - When the item has been dispatched, in response to **dispatchItem**.
+* **ItemReceived** - When the item has been received, in response to **receiveItem**.
+* **MessageSent** - When a user has sent a message, in response to **sendMessage**.
+* **RefundInitiated** - When the seller has initiated a refund, in response to **initiateRefund**.
+* **RefundConfirmed** - When a refund has been confirmed.
+
+## Commands handled
+
+### External (user)
+
+* **sendMessage** - Send a message to the other user, emits **MessageSent**.
+* **submitDeliveryDetails** - Used by the buyer to submit delivery details, emits **DeliveryDetailsSubmitted**.
+* **setDeliveryPrice** - Used by the seller to set the delivery price when delivery option is by negotiation, emits **DeliveryPriceUpdated**.
+* **submitPaymentDetails** - Used by the buyer to submit payment details.
+* **dispatchItem** - Used by the seller to say they have dispatched the item.
+* **receiveItem** - Used by the buyer to say they have received the item.
+* **initiateRefund** - Used by the seller to initiate a refund.
+
+## Events consumed
+
+### Item service
+
+* **AuctionFinished** - Creates the transaction.
+
+### Payment service
+
+* **ReceivedPayment** - Indicates the payment has been made, emits **PaymentConfirmed**.
+* **FailedPayment** - Indicates payment failed, emits **PaymentFailed**.
+* **MadeRefund** - Indicates a refund was made, emits **RefundConfirmed**.
+
diff --git a/docs/user-service.md b/docs/user-service.md
@@ -0,0 +1,18 @@
+#User service
+Handles different user accounts. *stub*
+
+## Queries handled
+* **getUser** Retrieve user given UUID
+* **createUser** Create a new user
+* **getUsers** Get all users on platform
+
+## Events emitted
+* **UserCreated** Emitted when a new user is created
+
+## Commands handled
+
+### External (user)
+
+## Events consumed
+
+