update readme file

Author: RustamovAkrom

README.md

@@ -1,3 +1,248 @@
-# Marketplace
+# 🛒 Marketplace — Modern E‑Commerce Backend Platform
 
-> E-commerce application in FastAPI
+**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.
+
+# 🧰 Used Technologies
+
+Below is the list of core technologies and dependencies used in this project, based on the project configuration:
+
+### 🔧 Runtime & Frameworks
+
+* **Python 3.12+** — [https://www.python.org/](https://www.python.org/)
+* **FastAPI** — [https://fastapi.tiangolo.com/](https://fastapi.tiangolo.com/)
+* **Uvicorn** — [https://www.uvicorn.org/](https://www.uvicorn.org/)
+* **SQLAlchemy 2.0** — [https://docs.sqlalchemy.org/](https://docs.sqlalchemy.org/)
+* **Alembic** — [https://alembic.sqlalchemy.org/](https://alembic.sqlalchemy.org/)
+
+### 📦 Async & Utilities
+
+* **aiofiles** — [https://github.com/Tinche/aiofiles](https://github.com/Tinche/aiofiles)
+* **httpx** — [https://www.python-httpx.org/](https://www.python-httpx.org/)
+* **orjson** — [https://github.com/ijl/orjson](https://github.com/ijl/orjson)
+* **argon2-cffi** — [https://argon2-cffi.readthedocs.io/](https://argon2-cffi.readthedocs.io/)
+* **passlib[bcrypt]** — [https://passlib.readthedocs.io/](https://passlib.readthedocs.io/)
+* **python-jose** — [https://github.com/mpdavis/python-jose](https://github.com/mpdavis/python-jose)
+* **python-multipart** — [https://andrew-d.github.io/python-multipart/](https://andrew-d.github.io/python-multipart/)
+* **pydantic-settings** — [https://docs.pydantic.dev/](https://docs.pydantic.dev/)
+* **python-dotenv** — [https://github.com/theskumar/python-dotenv](https://github.com/theskumar/python-dotenv)
+
+### 📨 Email & Background Tasks
+
+* **FastAPI-Mail** — [https://sabuhish.github.io/fastapi-mail/](https://sabuhish.github.io/fastapi-mail/)
+* **Celery** — [https://docs.celeryq.dev/](https://docs.celeryq.dev/)
+* **Flower (Celery Monitoring)** — [https://flower.readthedocs.io/](https://flower.readthedocs.io/)
+
+### 🧪 Testing
+
+* **pytest** — [https://docs.pytest.org/](https://docs.pytest.org/)
+* **pytest-asyncio** — [https://github.com/pytest-dev/pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio)
+* **pytest-cov** — [https://github.com/pytest-dev/pytest-cov](https://github.com/pytest-dev/pytest-cov)
+
+### 🛠 Development Tools
+
+* **black** — [https://github.com/psf/black](https://github.com/psf/black)
+* **isort** — [https://pycqa.github.io/isort/](https://pycqa.github.io/isort/)
+* **ruff** — [https://docs.astral.sh/ruff/](https://docs.astral.sh/ruff/)
+* **mypy** — [https://mypy-lang.org/](https://mypy-lang.org/)
+* **pre-commit** — [https://pre-commit.com/](https://pre-commit.com/)
+* **loguru** — [https://github.com/Delgan/loguru](https://github.com/Delgan/loguru)
+
+---
+
+## 🚀 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
+![](/docs/media/diagram.png)
+> 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
+
+```bash
+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
+
+---
+
+## ⚙️ Environment Variables Example (`.env-example`)
+
+```env
+# Use this file to configure your development environment
+# Copy it to .env and fill your credentials
+```
+
+## ▶️ Getting Started (Without Docker)
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/RustamovAkrom/Marketplace-FastAPI.git
+cd Marketplace-FastAPI
+```
+
+### 2. Create `.env` File
+
+```env
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db
+SECRET_KEY=your-secret-key
+DEBUG=true
+```
+
+### 3. Install Dependencies
+
+```bash
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+```
+
+### 4. Run Migrations
+
+```bash
+alembic upgrade head
+```
+
+### 5. Start Server
+
+```bash
+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:
+
+```bash
+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.

docs/media/diagram.png

@@ -5,6 +5,7 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
+    "aiofiles>=25.1.0",
     "aiosqlite>=0.21.0",
     "alembic>=1.17.2",
     "argon2-cffi>=25.1.0",
@@ -28,6 +29,7 @@ dependencies = [
     "pytest-cov>=7.0.0",
     "python-dotenv>=1.2.1",
     "python-jose[cryptography]>=3.5.0",
+    "python-multipart>=0.0.20",
     "ruff>=0.14.7",
     "types-python-jose>=3.5.0.20250531",
     "uvicorn[standard]>=0.38.0",

pyproject.toml

@@ -5,6 +5,9 @@
 
 BASE_DIR = Path(__file__).resolve().parent.parent.parent
 
+MEDIA_ROOT = BASE_DIR / "media"
+MEDIA_URL = "/media/"
+
 
 class BaseAppSettings(BaseSettings):
     # ENVIRONMENT

src/core/config.py

@@ -0,0 +1,59 @@
+# src/api/v1/upload.py
+from fastapi import APIRouter, Depends, HTTPException, UploadFile
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core import config
+from db.crud.base import get_crud_for_model  # универсальная функция для CRUD
+from db.dependencies.sessions import get_db_session
+from services.file_service import save_file
+
+router = APIRouter(prefix="/upload", tags=["Upload"])
+
+
+@router.post("/{model_name}/{instance_id}/{field_name}")
+async def upload_file(
+    model_name: str,
+    instance_id: int,
+    field_name: str,
+    file: UploadFile,
+    filetype: str = "image",
+    db: AsyncSession = Depends(get_db_session),
+):
+    """
+    Универсальный upload endpoint.
+    model_name: имя модели в lower_case
+    instance_id: ID объекта
+    field_name: имя поля модели для сохранения пути
+    """
+    # Получаем CRUD для модели
+    crud = get_crud_for_model(model_name, db)
+    if not crud:
+        raise HTTPException(
+            status_code=400, detail=f"Model '{model_name}' not supported"
+        )
+
+    # Получаем объект
+    instance = await crud.get_by_id(instance_id)
+    if not instance:
+        raise HTTPException(
+            status_code=404, detail=f"{model_name.capitalize()} not found"
+        )
+
+    # Сохраняем файл
+    relative_path = await save_file(file, model_name, instance_id, filetype)
+
+    # Обновляем поле модели
+    current_value = getattr(instance, field_name, None)
+    if isinstance(current_value, list):
+        # для множественных файлов
+        current_value.append(relative_path)
+        setattr(instance, field_name, current_value)
+    else:
+        # одно поле
+        setattr(instance, field_name, relative_path)
+
+    db.add(instance)
+    await db.commit()
+    await db.refresh(instance)
+
+    return {"url": f"{config.MEDIA_URL}{relative_path}", "field": field_name}

src/db/crud/base.py

@@ -0,0 +1,6 @@
+import uuid
+
+
+def generate_filename(original_name: str) -> str:
+    ext = original_name.split(".")[-1]
+    return f"{uuid.uuid4().hex}.{ext}"

src/utils/__init__.py

@@ -0,0 +1 @@
+def generate_random_code(): ...