Project Structure

fastapi-ecommerce-backend/
├── app/              # Routers — HTTP endpoints only, no business logic
├── services/         # Business logic — all @staticmethod methods
├── repositories/     # Raw SQLAlchemy queries only
├── models/           # ORM models: Client, Order, Product, Transaction, Category, OrderProduct
├── schemas/          # Pydantic v2 — request validation and response serialization
├── core/             # Config, 30+ custom exceptions, enums (Role, OrderStatus, etc.)
├── database/         # Async session, Unit of Work pattern
├── utils/            # JWT dependencies, WebSocket connection manager, structured logger
├── alembic/          # Database migrations
├── tests/            # pytest integration tests
├── celery_app.py     # Celery tasks (email sending)
├── Dockerfile
└── docker-compose.yml

Architecture

Router → Service → UnitOfWork → Repository → DB

• Router — handles HTTP only, delegates everything to services
• Service — all business logic, @staticmethod methods, always uses UnitOfWork
• UnitOfWork — async context manager, opens session, auto-commits on success, auto-rollbacks on exception
• Repository — raw SQLAlchemy queries, no logic
• Models — 6 ORM models with One-to-Many and Many-to-Many relationships

Key Features

• Auth & Security — JWT access + refresh token flow, bcrypt, email verification via UUID token stored in Redis (24h TTL), forgot/reset password via email
• RBAC — 3 roles (client / moderator / superadmin) with role-based endpoint protection
• Product Moderation — pending → accept / rejected workflow, reviewed by moderator or superadmin
• Soft Delete — clients soft-deleted via is_active flag; data preserved, hidden from all queries
• Caching — Redis with 60s TTL on list/stats endpoints, wildcard invalidation on every write
• Pagination — all list endpoints support limit and offset
• Order Flow — checkout validates stock, deducts balance, creates purchase transaction; refund restores balance and creates refund transaction
• Stripe Payments — PaymentIntent flow; client creates intent, Stripe confirms via webhook, balance topped up automatically
• WebSocket — persistent admin connection, broadcasts checkout notifications to all connected admins in real time
• Async Tasks — Celery + RabbitMQ for background email sending (verification, password reset, order status change)
• Product Quantity — checkout validates available stock, returns HTTP 400 if insufficient
• Pessimistic Locking — SELECT ... FOR UPDATE on all balance-changing operations to prevent race conditions
• Order State Machine — enforced transitions (pending → completed / cancelled, completed → cancelled only)
• Rate Limiting — Redis-based per-IP counter on login and forgot-password endpoints; max 5 requests / 60s, returns HTTP 429
• AI Integration — Groq API (LLaMA 3.3-70b-versatile) powers 4 features: personalized recommendations based on purchase history, semantic AI search, store assistant chatbot, and AI-generated product descriptions for admins
• Structured Logging — utils/logger.py with get_logger utility outputs timestamped logs to stdout; all services log key business events at INFO level, not-found cases at WARNING; plain reads are intentionally skipped to keep logs clean
• CI/CD — GitHub Actions runs 65 integration tests on every push and PR; on merge to main automatically deploys to AWS EC2 via SSH

CI/CD Pipeline

git push / pull request
        ↓
GitHub Actions — CI
  • spins up PostgreSQL 15 + Redis 7
  • runs alembic migrations
  • runs pytest (65 tests)
        ↓
merge to main
        ↓
GitHub Actions — CD
  • connects to AWS EC2 via SSH
  • git pull origin main
  • docker compose up --build -d

Data Models

Roles

First superadmin must be set directly in the database:

UPDATE clients SET role='superadmin' WHERE email='your@email.com';

API Endpoints

🔓 Public   🔒 Authenticated   🔑 Superadmin   🛡 Moderator (superadmin or moderator)

Auth

Client

Product

Order

Transaction

Payment (Stripe)

Category

AI

WebSocket

Running Locally

1. Clone and configure

git clone https://github.com/bogdan0089/fastapi-ecommerce-backend.git
cd fastapi-ecommerce-backend
cp .env.example .env
# fill in the required values in .env

2. Start with Docker

docker compose up --build

API: http://localhost:8000
Swagger UI: http://localhost:8000/docs

Alembic migrations run automatically on startup.

3. Run tests

pytest tests/ -v

4. Stripe webhook (local testing)

stripe listen --forward-to localhost:8000/payment/webhook

5. Migrations (manual)

alembic upgrade head
alembic revision --autogenerate -m "description"

Docker Services