BuyAnything Technical design

[lontivero]

ShopWare API client

The ShopWareApiClient (WalletWasabi/WebClients/ShopWare/ShopWareClient.cs) is an REST API client to https://shopware.stoplight.io/docs/store-api/ that includes the necessary calls to implement the BuyAnything feature. This is:

• Create Customer
• Create ShoppingCart
• Add product items to a ShoppingCart
• Create an Order (Checkout the shoppingCart)
• Get the Country ID by a given country name
• Add comments
• etc (we still don't know what else is needed for now)

BuyAnything Client

The BuyAnythingClient is a higher level client that abstracts most of the "low-level" details and implements:

• Create new "conversation"
• Update "conversation"
• TDB

BuyAnything Manager

This is the guy who really make the magic happen. This should be a periodic runner service which keeps track of the "conversations" buy pulling updates from time to time, saves the news and raise events every time there is something new.

The UI then sends command to the BuyAnythingManager and subscribes to the event that it raises.

 ┌────────────────────┐ Raise events      ┌──────────┐
 │ BuyAnythingManager ├──────────────────►│ The UI   │
 └─────────┬────▲─────┘                   └────┬─────┘
           │    │                              │
           │    │     Sends commands to        │
           │    └──────────────────────────────┘
           │
 ┌─────────▼──────────┐
 │ BuyAnythingClientr │
 └─────────┬──────────┘
           │
           │
           │
 ┌─────────▼──────────┐
 │ ShopWareApiClient  │
 └────────────────────┘

[lontivero]

BuyAnythingManager

This component is the one that the UI interacts with. The UI doesn't know anything about BuyAnythingClient or ShopWareApiClient.

BuyAnythingManager class is the only one that tracks conversations, this is:

• It loads the list of conversations from disk
• It saves the conversations to disk when they are created and every time something new happens to them (updates)
• It keeps a list in memory with all the conversations and adds new conversations to it.

Methods

• Create new conversation
• Update conversation (with a new message)
• Cancel conversation
• Get list of countries
• Get list of products (there are only three hardcoded)

Data structures

Conversation:

Depending on whether the context tokens expire or not the conversation identifier is the walletID plus the context token itself or the customer's email + password tuple.

 ┌────────────────┬────────┬────────────┬──────────────────┐
 │ ConversationID │ Status │ LastUpdate │ RawConversation  │
 └────────────────┴────────┴────────────┴──────────────────┘

• Status: this is the filed that indicates what the situation at the time during the buying workflow. It doesn't need to match with the shopware orders status. This is important because we don't want to get updates for conversations that were cancelled or finised, for example. The status can be:
  1. Started
  2. Finished
  3. Cancelled
  4. Waiting for updates
• LasUpdated: is the datetime of the las time we news something from the order and it is used to detect when something was updated on the shopinbit side.
• RawConversation: this is simply the whole unparsed/unprocessed text on the custom field. We need to append our own text to it before sending it to the server.

Note: lets use json serialization for this. It sucks but will give us a lot of flexibility to change things, we need that.

Workflow during lifetime

• Immediately after the BuyAnythingManager is created, it loads all the conversations from disk and put them in the conversations tracking list.
• Periodically it goes through the conversations list and fetch updates from the shopingbit server for all those conversations that are not cancelled or Finished/Completed. It updates the lastUpdated value and the RawConversation field. It notifies the UI by raising an event and updates the conversation on disk.
• After starting a new conversation successfully the conversations list must be updated and saved to disk

Tor

Because of the limited time we have have to implement this the first approach if to use .NET 7 WebProxy for socks, routing everything through Tor socks proxy.

Ideally we have to change the HttpClient by an IHttpClient instance and create new circuits for each customers.

Challenges!

Context Token expiration

If the context tokens expire then we not only need to log in all our customers immediately after creating the BuyAnythingManager but also need to detect when their context token expired so we can re-log them in. In fact, we have to detect that something was wrong, that the customer is not logged in, and log it again (and repeat the failing operation)

Logging

We need to add logs to BuyAnythingManager methods.

[lontivero]

  ┌─────────────┐                      ┌────────────────┐
  │  Started    ├──────────(Offer)────►│ OfferReceived  │
  └─────────────┘                      └───────┬────────┘
                                               │
                                               │ (AcceptOffer)
                                               ▼
                                       ┌────────────────┐
                                       │ OfferAccepted  │
                                       └───────┬────────┘
                                               │
                                               │ (ReceiveInvoice)
                                               ▼
  ┌───────────────┐                    ┌────────────────┐
  │ Now what?     │◄───────────────────┤ InvoiceReceived│
  └───────────────┘ (InvoiceExpiration)└───────┬────────┘
                                               │
                                               │ (Pay)
                                               ▼
                                       ┌──────────────────┐
                                       │ PaymentConfirmed │
                                       └───────┬──────────┘
                                               │
                                               │ (ShipProduct)
                                               ▼
                                       ┌──────────────────┐
                                       │ ProductShipped   │
                                       └──────────────────┘

[lontivero]