IR-ecommerce

NOTICE: THIS SITE IS DEAD DUE TO AWS INVOICE. RIP🙏.

Demo Website: IREC

Demo account (only view permission in admin page):

email: demo@email.com password: demo123456

NOTE: USE TEST CREDIT CARD TO MAKE PAYMENT 4242 4242 4242 4242

Check here for more info.

About This Project

This is a simple ecommerce project built mainly by Django Framework + few Javascript/jquery, using Bootstrap 4 template with Django template language.

As a hands-on project for a newbee developer (myself), if your are tired of writing those helloworld crap, looking for something more challenging to make use of your Django and overall web development skills, hope this project could be helpful as your reference.

Since I am exploring the right way to impelement those features, I am pretty sure there are many other better approaches. Please feel free to share your ideas and indicate my mistakes, which would be really really appreciated.

Sample Photos

Home - searching, category, trending items

Shop list - list items, sorting, searching, categorizing

Item detail - add shopping cart, add wishlist, check reviews, related products

Shopping cart - item crud operation

Checkout - select payment method, edit or add address

Guest checkout - add shipping address on checkout

Find order - guest retrieving order data, making payment/return item

Account center - change profile and password, list watch history in watched order

Account center orders - order status management, pay/refund/return etc, order detail, write review

Account center - shipping address management

Account wishlist - list wishlisted items

Account activation email - also use for changing account email and sending order status update to customer

Admin page - appearance, actions

Features

account center
- account registration with email activation (also used in changing email address)
- login with email address
- remember login
- change profile and password (based on ajax request)
- manage recipient addresses (based on ajax request)
- order management
- write review and rate stars for ordered items
- google recaptcha for login and register (django-recaptcha)
shop
- list and detail view for items
- add/remove item to/from wishlist
- save watch history
- show related item on detail page
- fulltext search (postgresql)
- item list view filter by sorting, category and tags
- item tags (django-taggit)
- recursive category (django-mptt)
shopping cart
- add item to shopping cart
- CRUD operation on shopping cart page (based on ajax request)
- guest checkout
order and payment
- payment with Stripe Checkout
- status management (django-fsm) (NOTE: this package is going to be deprecated soon, will transit to viewflow in the future)
customized admin
- use modern admin theme(django-simpleui)
- custom views and actions (shipping, cancel order, refund)
- autocomplete search (easy-select2)
others
- testing with factory_boy and faker
- rich text editor in admin page (django-ckeditor)
- use Sentry for monitoring
- deployment on EC2

Tech Stack

Django (>=3.1)
PostgresSQL
Redis
- web site caching
- login session cache
- message queue broker
- shopping cart, watch history, wishlist database
AWS S3
- media file storage
AWS SES (prod env only)
Celery
- async tasks
- periodic tasks / cron jobs
Docker

Architect

The project is deployed in an EC2 instance, and makes use of other AWS services such as S3 bucket for media file storage, RDS for postgres database, and SES for email sending.

For details on deployment please refer to this tutorial:

TestDriven.io

DB Design

NOTE All (except Category and User) models inherit from a base model which has 3 fields: created_at, updated_up, is_deleted

The relationship between Order and Payment could be 1to1 which is easier to manage, while on some EC sites there is an option to pay multiple orders together, here just leave as it is.

Other models such as Invoice, CancelRecord, RefundRecord are not implemented as those could be acheived on the Stripe dashboard.

Order State Management

The states of order is quite complecated, and varies depending on projects and developer. It was really a headache for me.

This chart is created based on some references and my trials and errors, might work for a small project, but definately could be improved and better.

The core idea is that the status of order and status of payment should be seperated as 2 fields (instead of 1 status field in the Order model, which did not work well), meanwhile intertwined with each other (dot line arrows), since the state of payment or order could be the signal or criteria to make actions to change either order or payment's state. To acheive those transitions between different states, works could be done by a user, an admin, or the system.

It is not necessary to add every ongoing state or every perfect tense state (which confused me a lot at the beginning), instead it should be decided based on a simple question: Do I need an action to make the transition here? In other words, if you found that you need 2 steps to acheive the next state, that probably means there should be one more state in the middle.

How To Start (Local Env)

First clone the repository:

$ git clone https://github.com/convers39/IR-ecommerce.git

Setup your local env file, in my example, the project folder tree looks as below, the env file located in core folder. The default location recognized by docker-compose file is the same directory with docker-compose (in this case the root dir), make sure you set the right file path for env file.

.
├── LICENSE
├── README.md
├── _samples
├── apps
│   ├── __init__.py
│   ├── account
│   ├── cart
│   ├── order
│   └── shop
│       ├── __init__.py
│       ├── admin.py
│       ├── apps.py
│       ├── context_processors.py
│       ├── managers.py
│       ├── migrations
│       ├── models.py
│       ├── signals.py
│       ├── tasks.py
│       ├── templatetags
│       ├── tests
│       │   ├── __init__.py
│       │   ├── factory.py
│       │   ├── test_models.py
│       │   ├── test_urls.py
│       │   └── test_views.py
│       ├── urls.py
│       └── views.py
├── core
│   ├── __init__.py
│   ├── asgi.py
│   ├── celery.py
│   ├── env
│   │   ├── env.local
│   │   ├── env.prod
│   │   ├── env.prod.proxy-companion
│   │   ├── env.staging
│   │   ├── env.staging.proxy-companion
│   ├── settings
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── local.py
│   │   ├── prod.py
│   │   └── testing.py
│   ├── urls.py
│   └── wsgi.py
├── db
│   ├── __init__.py
│   └── base_model.py
├── docker-compose.yml
├── dockerfile
├── manage.py
├── media
├── requirements.txt
├── static
│   ├── css
│   ├── icons
│   ├── img
│   ├── js
│   └── vendor
└── templates
    ├── account
    ├── base.html
    ├── cart
    ├── index.html
    ├── order
    └── shop

Then you will need to write down credentials of database, mail server, AWS s3 bucket and Stripe API keys in your env file, and in your settings you can obtain those values, for instance:

# core/settings/base.py
# ...
# Mail server settings will be different depending on which mail service you use
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = os.environ.get('EMAIL_HOST')
EMAIL_PORT = os.environ.get('EMAIL_PORT')
EMAIL_USE_TLS = os.environ.get('EMAIL_USE_TLS')
EMAIL_HOST_USER = os.environ.get('EMAIL_HOST_USER')
EMAIL_FROM = os.environ.get('EMAIL_FROM')
EMAIL_HOST_PASSWORD = os.environ.get('EMAIL_HOST_PASSWORD')

# Use postgresql as database, SQLite is not tested, and fulltext search is not supported
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST'),
        'PORT': os.environ.get('DB_PORT'),
    }
}

# AWS setting
AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID')
AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY')
AWS_STORAGE_BUCKET_NAME = os.environ.get('AWS_STORAGE_BUCKET_NAME')
AWS_S3_REGION_NAME = os.environ.get('AWS_S3_REGION_NAME')  # change to your region
AWS_S3_SIGNATURE_VERSION = os.environ.get('AWS_S3_SIGNATURE_VERSION')
AWS_S3_FILE_OVERWRITE = True # either true or false is ok

# stripe key
STRIPE_SECRET_KEY = os.environ.get('STRIPE_SECRET_KEY')
STRIPE_PUBLIC_KEY = os.environ.get('STRIPE_PUBLIC_KEY')
WEBHOOK_SECRET = os.environ.get('WEBHOOK_SECRET')

Now build the image and compose up the containers, add --build flag to compose up when rebuild is needed.

$ docker build .
$ docker-compose -f docker-compose.yml up

Start an empowered interactive shell in django container (provided by django-extensions), use the container name (django in this project)

$ docker exec -it <django> bash
$ python manage.py shell_plus

Access to Postgresql and Redis (Postgresql container is removed in prod setup as using AWS RDS for DB)

$ docker exec -it <pgdb> psql -U <username> <password>

$ docker exec -it <redis> sh
$ redis-cli

To run a test, specify a setting file (might run to errors with debug toolbar if not using testing settings, which forces to turn off DEBUG)

$ python manage.py test <appname> --settings=core.settings.testing

Future Updates

Currently on plan:

guest shopping cart and checkout
deployment a demo site + deployment setup
image resize on upload
language support for Chinese and Japanese
filters on shop item list and account center
third party Oauth login
coupon apply on shopping cart page

Template credits:

BOOTSTRAP TEMPLE

convers39 / IR-ecommerce