KXRS · E-commerce platform

A Django storefront where browsing, selling and ordering share one domain model.

✦ Interactive showcase · REST API · CI checks

KXRS / SHOP is a portfolio-ready e-commerce lab: customers get a catalog, basket and order flow; sellers get a store, product management and discounts; developers get a browsable API and a compact, easy-to-follow architecture.

✨ What to explore first

Surface	What it demonstrates
Interactive showcase	Clickable customer/seller/API flows, architecture map and a live sample basket
Storefront UI	Catalog, product detail, basket, order list and seller profile templates
REST API	Users, products, baskets, orders and cookie-based JWT auth under /api/
Admin + docs	Django admin for the domain and Swagger UI at /swagger/

Product story

flowchart LR
    A[Customer] --> B[Catalog]
    B --> C[Basket]
    C --> D[Order]
    D --> E[Pay + delivery]
    F[Seller] --> G[Store]
    G --> H[Products + discounts]
    H --> B
    I[REST clients] --> J[/api/]
    J --> K[(PostgreSQL)]
    B --> K
    D --> K

Loading

Customer flow

1. Register or sign in.
2. Browse active products from other stores.
3. Add and remove quantities in a personal basket.
4. Create an order, pay it and track delivery status.

Seller flow

1. Become a seller and create one store.
2. Manage products from the seller profile.
3. Add product data such as category, brand, stock, material and rating.
4. Attach a percentage or fixed discount to a product.

Visual tour

Open the interactive showcase to explore the flows instead of only reading screenshots.

To publish it from this repository, set Settings → Pages → Source: GitHub Actions once. The workflow in .github/workflows/pages.yml then updates the showcase on every push to main.

Quick start

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r req.txt
cp .env.example .env

docker compose up -d
python manage.py migrate
python manage.py loaddata db_dump.json
python manage.py runserver

Then open:

• storefront: http://127.0.0.1:8000/shop/
• API: http://127.0.0.1:8000/api/
• Swagger: http://127.0.0.1:8000/swagger/

The included Docker Compose file exposes PostgreSQL on port 1234. For production, move secrets to environment variables and turn off Django debug mode before deployment.

API map

Route	Purpose
/api/auth/login/	Login and issue JWT cookies
/api/auth/refresh/	Rotate/refresh the access token
/api/product/list/	List active product data
/api/product/	Router-backed product CRUD
/api/basket/	Basket list and CRUD actions
/api/order/	Orders and order items
/api/user/	Users and filterable user list
/swagger/	Interactive API documentation

Project map

main/              Django project settings and root routes
shop/models/       users, stores, products, discounts, baskets and orders
shop/views/        storefront and seller-facing workflows
shop/api/          serializers, viewsets, filters, permissions and JWT auth
shop/templates/    server-rendered UI
static/            styles and application images
media/             sample user, store and product uploads
docs/index.html    self-contained interactive GitHub Pages showcase

Development checks

poetry run black --check .
poetry run flake8 .
poetry run python manage.py test shop.api.tests

---

Detailed project notes — original model and screen documentation

E-commerce Platform Functionality Overview

Our platform allows users to register, browse products, and make purchases. Additionally, users can become sellers, create their own stores, and offer discounts on their products. The main features include:

General User Features:

• Users can browse product listings but cannot add other users' products to their carts.
• The cart exists as a single instance per user and can only be recreated after completing an order.
• A dedicated cart page is available for users to view their selected products.
• Users can sort the product list for better navigation (upcoming feature).

Seller Features:

• Users can convert their account into a seller account.
• Sellers can create their own store (limited to one store per user).
• Stores display the seller’s products, allowing customers to browse and purchase.
• Sellers can add new products to their store.
• Discounts can be applied to products, and these discounts will be visible in the user profile.

Product & Store Management:

• Users can add and remove products from their cart (upcoming feature).
• Discounts created by sellers currently do not attach to products (to be fixed).
• Store pages will showcase the seller’s store and its products instead of listing all products separately.
• This functionality ensures a seamless shopping and selling experience while maintaining structured store management for sellers.

Installation and Setup

0. Deploy virtual environment:

    python -m venv venv

1. Install dependencies:

   pip install -r req.txt

2. Set up the database in Docker:

   docker compose up -d

3. Load the database dump:

   python manage.py loaddata db_dump.json

4. Run the project:

   python manage.py runserver

Models

Users (shop.user)

• Fields:
  • username: User's username.
  • password: User's password.
  • email: User's email.
  • is_sealer: Flag indicating whether the user is a seller.
  • phone: User's phone number.
  • photo: User's photo.
  • is_active: User's active status flag.
  • date_joined: User's registration date.

Stores (shop.storename)

• Fields:
  • name: Store name.
  • is_active: Store's active status flag.
  • logo: Store's logo.

Seller Profiles (shop.sellerprofile)

• Fields:
  • user: Reference to the user (seller).
  • store_name: Reference to the store.
  • description: Store description.
  • rating: Store rating.
  • created_at: Profile creation date.
  • updated_at: Profile last update date.

Products (shop.product)

• Fields:
  • name: Product name.
  • description: Product description.
  • price: Product price.
  • owner: Product owner (seller).
  • photo: Product photo.
  • created_at: Product creation date.
  • updated_at: Product last update date.
  • category: Product category.
  • brand: Product brand.
  • quantity_in_stock: Product stock quantity.
  • is_active: Product's active status flag.
  • color: Product color.
  • material: Product material.
  • rating: Product rating.
  • discount: Product discount.

Discounts (shop.discount)

• Fields:
  • name: Discount name.
  • description: Discount description.
  • discount_type: Discount type (percentage or fixed).
  • value: Discount value.
  • start_date: Discount start date.
  • end_date: Discount end date.
  • category: Product category the discount applies to.
  • product: Product the discount applies to.

Orders (shop.order)

• Fields:
  • user: User who placed the order.
  • status: Order status (e.g., "pending", "paid", "completed").
  • delivery_date: Order delivery date.
  • created_at: Order creation date.
  • updated_at: Order last update date.

Order Items (shop.orderitem)

• Fields:
  • order: Order the item belongs to.
  • product: Product in the order.
  • quantity: Product quantity in the order.

Baskets (shop.basket)

• Fields:
  • user: User the basket belongs to.

Main menu view

Basker

Order List