Marsea Storefront

A full-stack e-commerce storefront with a responsive React interface, a FastAPI checkout service, WayForPay payments, Redis-backed order state, and Telegram order notifications.

Overview

Marsea is a production-oriented online store implementation. The frontend provides the product and checkout experience, while the backend prepares payments, handles approved callbacks, temporarily stores order data, and sends order details to Telegram.

Highlights

• Responsive product catalog and product detail views
• Shopping cart and checkout flow
• Nova Poshta branch and courier delivery options
• Card payments through WayForPay
• Cash-on-delivery order flow
• Telegram notifications for confirmed orders
• Redis-backed temporary order storage
• Server-authoritative product prices and order totals
• Verified and idempotent WayForPay callbacks
• Dockerized frontend, backend, Redis, and reverse-proxy stack

Architecture

React storefront
    |
    | POST /api/pay
    v
FastAPI checkout service
    |-- Redis: temporary order state
    |-- WayForPay: signed payment request
    |-- Telegram: confirmed order notification
    |
    | POST /api/pay-callback
    v
Approved payment processing

Components

• frontend/ — React application, catalog, cart, delivery, and checkout UI
• backend/ — FastAPI payment and order-notification service
• redis — temporary storage for pending card-payment orders
• docker-compose.yml — application stack and internal network
• Nginx Proxy Manager — HTTP/HTTPS routing for deployed environments

Tech Stack

Frontend

• React 19
• React Router
• Axios
• React Select
• Swiper
• CSS

Backend

• Python
• FastAPI
• Pydantic
• Uvicorn / Gunicorn
• Redis
• HTTPX / Requests

Infrastructure and integrations

• Docker Compose
• Redis 7
• WayForPay
• Telegram Bot API
• Nginx Proxy Manager

Checkout Flow

1. The customer selects products and provides contact and delivery details.
2. The frontend submits the order to POST /api/pay.
3. Cash-on-delivery orders are sent directly to the configured Telegram chat.
4. Card orders receive WayForPay form parameters and are temporarily stored in Redis.
5. WayForPay calls POST /api/pay-callback after payment processing.
6. The backend verifies the callback signature, merchant, amount, and currency.
7. Approved orders are atomically claimed from Redis and sent to Telegram once.
8. The backend returns a signed WayForPay acknowledgement.

API

Create an order or payment request

POST /api/pay

Supports:

• card — prepares a WayForPay payment request
• cod — creates a cash-on-delivery order

Process the payment callback

POST /api/pay-callback

Verifies the WayForPay HMAC signature and forwards matching approved orders to Telegram. Duplicate callbacks are acknowledged without duplicating the order notification.

Interactive FastAPI documentation is available at /api/docs in the proxied deployment.

Configuration

The backend is configured through environment variables. Required values depend on the enabled checkout flow:

Variable	Purpose
MERCHANT_ACCOUNT	WayForPay merchant account
MERCHANT_SECRET	WayForPay request-signing secret
WEBSITE_DOMAIN	Store domain used in payment requests
RETURN_URL	Customer return URL after payment
CALLBACK_URL	WayForPay server callback URL
BOT_TOKEN	Telegram bot token
ORDERS_CHAT	Telegram chat for order notifications
REDIS_HOST	Redis hostname; redis under Docker Compose

Keep real credentials in a local environment file or a deployment secret store. Never commit them to Git.

Copy backend/.env.example to backend/.env for local development and replace the placeholders. The example file contains no usable credentials.

Run with Docker

Prerequisites:

• Docker
• Docker Compose
• Required backend environment variables

Start the stack:

docker compose up --build -d

View logs:

docker compose logs -f backend frontend

Stop the stack:

docker compose down

Local Development

Run the backend:

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Run the frontend in another terminal:

cd frontend
npm install
npm start

The frontend development server runs on http://localhost:3000.

Tests and CI

Run the backend security and checkout tests:

cd backend
python -m unittest discover -s tests -v

Build the frontend:

cd frontend
npm ci
npm run build

GitHub Actions runs the backend suite on Python 3.11 and 3.12 and verifies the production frontend build for every pull request and push to main.

Repository Structure

.
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   └── utils/
│   ├── tests/
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── public/
│   ├── src/
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
└── README.md