freshcom / freshcom-api

Deprecated

Freshcom

Fast, scalable and extensible eCommerce backend in Elixir.

Please see an overview of freshcom here.

Getting Started

External Dependencies

Freshcom requires the following external dependencies to work:

• Postgres for event store and projections
• Redis for write side state storage

Setup

1. Install Mix Depedencies

$ git clone https://github.com/freshcom/freshcom
$ cd freshcom
$ mix deps.get

2. Set Environment Variables

Once all the mix dependencies are installed we need to config the environment variables. Please copy paste .env.example and rename it to .env add in all the relevant environment variables. Then run source .env to set all the variables.

3. Setup Database

Setup the database with mix freshcom.setup which will do the following for you:

• Create the projection (read side) database and run all the relevant migrations
• Create and initialize the eventstore (write side) database

Run

Once you have everything setup you can get into iex with iex -S mix and try calling functions on the top level modules to see if things works properly. For example to create a user:

req = %Request{
  fields: %{
    "name" => "Demo User",
    "username" => "[email protected]",
    "email" => "[email protected]",
    "password" => "test1234",
    "is_term_accepted" => true
  },
  _role_: "system"
}

{:ok, %{data: user}} = Freshcom.Identity.register_user(req)

Roadmap

Base

• Filter
• Include
• Pagination
• I18N
• Search
• Sort
• Store
• Validation

Services

• Identity (Completed)
• Goods (In Progress) (30%)
• Inventory
• Catalogue
• CRM
• Finance
• Storefront
• Fulfillment
• Notification

Learn more

• Documentation: http://www.comingsoon.io/

Contact

Any question or feedback feel free to find me in the Elixir Slack Channel @rbao, will usually respond within few hours in PST timezone day time.

freshcom-api's Issues

As an administrator, I can change the status and role of an existing user

Account should have an attribute that indicate whether its ready to process live transaction

We should add a new attribute called ready_for_live_transaction attribute to account.

The new attribute will be useful for Dashboard where if an account is not yet ready for live transaction then we will show their test data by default, if it is then we will show live data by default. User can still toggle between live and test data using the view test data button in the Dashboard.

Test account will always have ready_for_live_transaction set to false

Remove hard dependency on Postmark

Lets use plain SMTP for global email sending so that we don't depend on postmark's templating system

Authentication plug should be improved

Right now endpoints that do not require authentication can be specified by passing an array of path to the plug, this should be improved so that instead of passing path we should pass in both http method and the path.

Add task for better sample data

Add timezone for user

Allow create return package

When in test mode SMS should not actually be sent

Rework storefront policy

Right now a guest user can change any cart as long as they have the ID, we should make this more strict by only allow guest user edit a cart that have customer_id: nil

Are there plans for subscription payment model?

Currently, the API supports fixed, variable, and wholesale pricing. Are there any plans to support a subscription model?

For example, a store offers subscribers access to all digital products with lifetime updates as long as they are subscribed. Once they stop subscribing, they can no longer receive updates for downloaded items, nor can they download new items.

An example of a subscription for physical items would be a bakery that offers a surprise assortment of goods delivered to the customer at predetermined intervals.

Parameters would include commitment and frequency of payment. These differ, as someone can have an annual commitment but pay in monthly installments, or vice-versa. Frequencies could include weekly, bi-weekly, monthly, quarterly, and annually.

Subscription models are very popular today, and would be an important addition to the Freshcom API.

As an administrator, I can add other global user to my account

• I will need to enter the Email and the role for the user
• If email does not belong to any registered global user, a email will be sent to the target email to prompt the user to sign up as a global user, once the user signup they will be added to the account automatically.
• If email belongs to a registered global user, a email will be sent to the target email to notify the user has been added to the account

implement expiry date for email verification token

Layer refactor

The goal of this refactor is to:

• Move Repetitive code to a central place
• Use elixir formatter for format code
• Add more domain layer test
• Add more documentation
• Move functions to its appropriate module and layers

As an administrator, I can create account user

I should be able to enter the following information of that user:

• Username
• Email
• Name
• Password
• Role

Username and email can be the same.

As an administrator, I can change the name and password of account user

Allow update return item

When in test mode email should not be send

In test mode, when a email is trigger a email resource will be created but it should not be sent.

Unable to activate product with multiple price

Allow multiple point account per customer

Right now we assume each customer only have on point account, but we should allow customer to have multiple point account, for example one for store credit, one for loyalty points... etc

Allow update get return package

Deeply nested include not getting translated

including memberships.product for product collection results in non-translated product resource

Fix product combo pricing

Right now product combo is bugged and can't be added to an order. Product combo use to have very complicated pricing model where each item will have a price that is the child of the parent product combo's price.

We want to re-design this so that product item can no longer have price them self, the price will always be associated with a product combo but each item will have a price_proportion_index (PPI) to represent the price of it compare to other item in the same combo.

Consider the following example of a fruit combo:

• It contain 3 fruits: apple, orange and lemon
• Price of the entire combo is $10
• apple's PPI is 30
• orange's PPI is 60
• lemon's PPI is 70

When this combo is added to an order the following line item tree should be build:

• Fruit Combo x 1 ..... $10
  • Apple x 1 ..... $1.88
  • Orange x 1 ..... $3.75
  • Lemon x 1 ..... $4.37

Each line item's sub total is calculated by using its item's PPI divided by the total PPI times the combo price. In the case of the apple it is 30/(30+60+70) * $10 = $1.88.

The last line item will always take the remaining amount left without using PPI as there could be some rounding problems. In this example, If we use PPI and round to 2 decimals then the sub total for lemon is actually $4.38, but if we use this then the tree doesn't balance because the total of all three fruits end up to be $10.01 which is 0.01 off, this is due to the rounding of both Apple and Lemon which is not acceptable.

Note that the PPI is different than the actual price, because a combo could have multiple prices, but the assumption here is the even tho the price is different the price proportion of each item stays the same.

All validation should use :code instead of :validation

:validation is the phoenix default, but sometime does not make much sense, for example errors: {"Card is declined, [validation: :card_declined]} is not as understandable since we are not actually validating the card ourself, its more readable to have errors: {"Card is declined, [code: :card_declined]}.

When a new primary card is set for a owner the old one should have primary set to false

Right now if we try to make a new card as primary, we end up with two primary card, unacceptable!

implement expiry date for password reset token

Allow update return package

Event balance.payment.create.before should be removed

Right now this event is only being subscribed by storefront context, but the logic there can easily be moved to subscribe for balance:payment.create.success instead

Domain layer update and delete function should accept identifiers instead of just ID

instead of update_xxxxx(id, fields, opts) where id is a string we should change so that it accept a map of identifiers for example %{ id: "id", status: "cart" } so that we implement "this user is only allowed to update resource status x" much easier

When a user with no permissions tries to uses PATCH /users/:id it should return 403

Right now when a user with no permission tries to uses PATCH /users/:id it would actually ignore the :id and update the user itself which has no security concern but very confusing

When creating managed user the response role attribute is always nil

right now the role attribute is always nil, it should not be nil and should return the correct role the newly created managed user

Domain layer should allow getting resource by nil

Because Repo.get_by cannot compared for nil, so we need to write extra code to handle when comparing finding resource base on some attribute being nil

Should allow client to create email verification token even if its using PAT

Right now client must use a UAT in order to create email verification token, we want to allow client use PAT, this is to cover the use case where some store do not auto login user right after registration which means client will never have access to a UAT, but still want give user a way to trigger resend of email verification.

Implement cursor based pagination

Allow user to sign up

As a marketing specialist, I should be able to add a product combo with customization

This will be a new product kind namely: comboWithCustomization.

This kind of product is useful for cases where a product combo consist of items that are customizable by the customer. A good example is a Mcdonalds combo lets say the big mac combo. The burger is set, but the fries is customizable where the customer can opt for large fries, similar for drink customer can not only choose drink but can also opt for large drink.

The resulting order line item tree should be like the following:

• Customized Big Mac Combo x 1 ------------- $10.99
  • Big Mac Combo x 1 -------- $9.99 (Base combo)
  • Large Fries x 1 ---------- $1.00 (Customizable item)
  • Large Drink -------------- $1.00 (Customizable item)
  • Coke x 1 ----------------- $0.00 (Customizable item)

We will call the item that is added under the combo as customizable item, each customizable item is actually a product, for now we only support simple product as customizable item.

In order to achieve this, a new resource ProductCustomizationGroup and ProductCustomizationGroupMembership need to be created with structure like the following:

{
  "id": "39bc17e7-cd32-4f2b-9711-ffe71f6d9f39"
  "type": "ProductCustomizationGroup",
  "attributes": {
    "name": "Drink",
    "maxiumSelect": 3, // Indicates customer cannot select more than 3 products from this group
    "minimumSelect": 1  // Indicates customer must at least select 1 products from this group
  },
  "relationships": {
    "product": {
      "data": { "id": "39bc17e7-cd32-4f2b-9711-ffe71f6d9f37", "type": "Product" }
    }
  }
}

{
  "type": "ProductCustomizationGroupMembership",
  "attributes": {
    "sortIndex": 1000,
    "default": false, // Indicates whether this is the default selected for the group
    "minimumOrderQuantity": 1,
    "maximumOrderQuantity": 2
  },
  "relationships": {
    "product": {
      "data": { "id": "b881ee15-5a36-4a94-b8d8-7f2ec631486b", "type": "Product" }
    },
    "price": {
      "data": { "id": "31abfc62-0099-4088-8e60-915e87a578b2", "type": "Price" }
    }
  }
}

The product that is associated to the ProductCustomizationGroupMembership is what we called the customizable item. The relationsips between the resources are as follow:

• Each product combo with customization has many customization group
• Each product combo with customization has many prices which act as the base price for the combo
• Each customization group has many membership
• Each customization group membership points to a simple product and optionally points to a price

When a product combo with customization is added to cart the default customization item for each customization group is added. If there is no default then that group will not have anything added. It is then up to the client to promopt the customer to select additional customization item from each customization group and add them to the order line item tree. We will not actually validate whether a customer have selected the minimum required item from each customization group, for now this will be the responsiblity of the client.

For the big mac combo example we can use the following resources to make it happen:

• kind: "comboWithCustomization", name: "Customized Big Mac Combo", Price: $9.99
• 3 customization groups:
  • Name: "Fries Size"; with 3 memberships:
    • Product: "Small Fries"; Price: $0.00
    • Product: "Medium Fries": Price: $0.00; default
    • Product: "Large Fries": Price: $1.00
  • Name: "Drink Size"; with 3 memberships:
    • Product: "Small Drink"; Price: $0.00
    • Product: "Medium Drink"; Price: $0.00; default
    • Product: "Large Drink"; Price: $1.00
  • Name: "Drink"; with 3 memberships:
    • Product: "Coke"; Price: $0.00
    • Product: "Sprit"; Price: $0.00
    • Product: "Orange Juice"; Price: $0.00

When this product combo with customization is added the initial order line item tree is the following:

• Customized Big Mac Combo x 1 ------------- $9.99
  • Big Mac Combo x 1 -------- $9.99
  • Medium Fries x 1 --------- $0.00
  • Medium Drink x 1 --------- $0.00

The client should then prompt the customer to customize their fries size, drink size and drink, and update the order line item tree accordingly

• Customized Big Mac Combo x 1 ------------- $10.99
  • Big Mac Combo x 1 -------- $9.99
  • Large Fries x 1 ---------- $1.00
  • Medium Drink x 1 --------- $0.00
  • Coke x 1 ----------------- $0.00

v0.2.0 Release

The goal of v0.2.0 is to keep current functionality but adding more test and finish all the documentation.

v0.2.0 will include refactor, additional unit test, integration test and documentation update

• Identity
  • Refactor
  • Test
  • Documentation
• Goods
  • Refactor
  • Test
  • Documentation
• Storefront
  • Refactor
  • Test
  • Documentation
• Catalogue
  • Refactor
  • Test
  • Documentation
• CRM
  • Refactor
  • Test
  • Documentation
• Balance
  • Refactor
  • Test
  • Documentation
• Fulfillment
  • Refactor
  • Test
  • Documentation
• File Storage
  • Refactor
  • Test
  • Documentation
• Notification
  • Refactor
  • Test
  • Documentation

Separate account to two different model

We should introduce a new model called Brand which only contain attributes of account that is public sharable

Improve test coverage to 70%

Right now we are at around 60% for test coverage, need to have at least 70%.