🛒 Marketplace — Modern E‑Commerce Backend Platform

Marketplace is a high‑performance, scalable, and modular e‑commerce backend built with FastAPI. It provides a fully structured architecture that covers every essential part of an online marketplace: user authentication, product catalog, carts, orders, delivery logistics, image upload system, and review management.

Designed following clean architecture principles, the project is maintainable, extendable, and production‑ready.

🚀 Features

👤 Users & Authentication

• User registration & login

• Logout and token revocation

• Refresh token workflow

• Password recovery via email

• Secure JWT‑based authentication (access + refresh tokens)

• Role system with permissions:

  • Buyer
  • Seller
  • Courier
  • Admin

---

🔐 Security

• Password hashing with bcrypt
• Revoked token tracking (logout / logout_all)
• Role‑based access control
• Strict Pydantic validation for all input/output data
• Secure and isolated file upload handling

---

💾 Tech Stack

Layer	Technologies
Backend	FastAPI, SQLAlchemy 2.0, Alembic
Database	PostgreSQL
Async	asyncpg, aiofiles
Authentication	OAuth2, JWT (Access & Refresh)
Caching (optional)	Redis
File Storage	/media directory with hashed filenames
Testing	Pytest
DevOps (optional)	GitHub Actions

---

🗄️ Database SQL Diagram

Project SQL diagram overview

Core Tables

• users
• sellers
• couriers
• delivery_addresses
• deliveries
• product_variants
• products
• product_images
• orders
• order_items
• brands
• categories
• carts
• cart_items
• promo_codes

---

📂 Project Structure

src/
├── api/
│ └── v1/
│ ├── auth/
│ ├── users/
│ ├── products/
│ ├── categories/
│ ├── seller/
│ ├── courier/
│ ├── orders/
│ └── delivery/
├── core/
│ ├── config.py
│ └── security.py
├── db/
│ ├── session.py
│ ├── base.py
│ └── models/
│ ├── users.py
│ ├── products.py
│ ├── categories.py
│ ├── brands.py
│ ├── cart.py
│ ├── orders.py
│ ├── delivery.py
│ ├── seller_profile.py
│ ├── courier_profile.py
│ └── review.py
├── services/
└── media/

---

🧠 Architecture

✔ Clean Architecture

• Clear separation between API, services, repositories, and database models
• Easy to extend and maintain

✔ Modular & Scalable

• Each domain (products, orders, delivery, etc.) is fully isolated
• Can be easily split into microservices (catalog, delivery, payments, etc.)

✔ Async‑first Design

• High throughput thanks to async stack
• Perfect for real‑time tasks such as courier tracking

---

▶️ Getting Started (Without Docker)

1. Clone Repository

git clone https://github.com/RustamovAkrom/Marketplace-FastAPI.git
cd Marketplace-FastAPI

2. Create .env File

DATABASE_URL=postgresql+asyncpg://user:pass@localhost/dbSECRET_KEY=your-secret-keyDEBUG=true

3. Install Dependencies

python -m venv venv
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
pip install -r requirements.txt

4. Run Migrations

alembic upgrade head

5. Start Server

uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

6. Open API Docs

http://localhost:8000/docs

---

🧪 Tests

Run all tests using:

pytest -vv

---

👨‍💻 Author

Akrom — Backend developer passionate about scalable architecture, clean code, and modern engineering practices. Building a production‑ready e‑commerce backend for real-world use and portfolio purposes.

---

📄 License

MIT License