docs: add comprehensive project documentation and API reference to README

README.md

@@ -1 +1,119 @@
-# seller_central_backend
+# Seller Central Backend
+
+A robust Django-based backend REST API for **Seller Central**, a web platform designed to streamline and empower suppliers. This backend supports registration, mock OTP verification, profile completion, product catalog management, order fulfillment cycles, customer returns, and financial transactions.
+
+---
+
+## 🛠️ Architecture & Technology Stack
+- **Framework**: Django & Django REST Framework (DRF)
+- **Database**: SQLite (default, easily configured for PostgreSQL/MySQL)
+- **Containerization**: Docker & Docker Compose
+- **Testing Framework**: Pytest with `pytest-django`
+- **CORS Support**: Configured for cross-origin frontend communication (`django-cors-headers`)
+
+---
+
+## 📦 Core E2E Modules & Business Logic
+
+### 1. Onboarding & Authentication
+- **Registration & Login**: Secure user registration and login endpoints utilizing Django's built-in authentication system.
+- **OTP Verification**: A simulated 2FA verification system (mock code: `123456`) that verifies onboarding/logins.
+- **Detailed Profiles**: Stores supplier coordinates (latitude/longitude), contact details, store branding details, and document references (Aadhar, PAN, and verified GSTIN).
+
+### 2. Product Catalog
+- **CRUD Operations**: Complete management of products, including title, category, price, stock, and SKU details.
+- **Bulk Upload**: Batch create products using a structured JSON payload to efficiently scale inventory.
+
+### 3. Order Management & Fulfillment
+- **Fulfillment Pipeline**: Transition orders through realistic stages:
+  `Pending Acceptance ➡️ Ready to Ship ➡️ Shipped ➡️ Delivered`
+- **Actions**: Suppliers can accept or reject pending orders. Accepting automatically assigns tracking numbers, shipping carriers, and estimates transit times.
+
+### 4. Returns & Customer Service
+- **Return Processing**: Suppliers can inspect customer returns, view return reasons, and track return packages.
+- **Resolution**: Actions to approve (marks status as `In Transit`) or reject returns.
+
+### 5. Wallet & Payout System
+- **Financial Ledger**: Tracks outstanding payouts and total withdrawn balances.
+- **Payout Withdrawals**: Securely requests withdraws from outstanding balances, generating transaction receipts (`TX-XXXX`) for audit trails.
+
+---
+
+## 🗺️ API Reference
+
+### Authentication & Profile
+- **`POST /api/auth/register/`**: Register a new supplier.
+- **`POST /api/auth/login/`**: Authenticate and initiate a session.
+- **`POST /api/auth/verify-otp/`**: Validate verification codes (use code `123456` for successful verification).
+- **`GET /api/profile/`**: Retrieve the authenticated profile.
+- **`PUT /api/profile/`**: Update GSTIN, bank details, and business settings.
+
+### Products Catalog
+- **`GET /api/products/`**: List all products owned by the supplier.
+- **`POST /api/products/`**: Create a new product.
+- **`DELETE /api/products/<id>/`**: Delete a product.
+- **`POST /api/products/bulk-upload/`**: Bulk create products in a single call.
+
+### Order Processing
+- **`GET /api/orders/`**: List all orders.
+- **`POST /api/orders/<id>/accept/`**: Accept a pending order (updates carrier & tracking).
+- **`POST /api/orders/<id>/reject/`**: Reject a pending order.
+
+### Customer Returns
+- **`GET /api/returns/`**: List return requests.
+- **`POST /api/returns/<id>/action/`**: Approve or reject a return request.
+
+### Wallet & Financials
+- **`GET /api/wallet/`**: Retrieve wallet balance and transactions list.
+- **`POST /api/wallet/withdraw/`**: Request payout/withdrawal.
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python 3.12+
+- Docker & Docker Compose (Optional)
+
+### Local Setup
+1. **Clone the Repository** and navigate to the project directory:
+   ```bash
+   git clone <repo_url>
+   cd seller_central_backend
+   ```
+2. **Set up Virtual Environment**:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+3. **Install Dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+4. **Run Migrations**:
+   ```bash
+   python manage.py migrate
+   ```
+5. **Run the Development Server**:
+   ```bash
+   python manage.py runserver
+   ```
+   The backend will be running at `http://127.0.0.1:8000/`.
+
+---
+
+## 🐳 Docker Deployment
+You can build and run the entire stack inside Docker containers:
+```bash
+docker-compose up --build
+```
+This serves the application on port `8000`.
+
+---
+
+## 🧪 Running Tests
+We use `pytest` for automated test coverage of authentication, profile updates, products CRUD, bulk uploads, order state transitions, and payouts.
+To execute tests, run:
+```bash
+pytest
+```