diff --git a/README.es.md b/README.es.md
new file mode 100644
index 0000000..0743764
--- /dev/null
+++ b/README.es.md
@@ -0,0 +1,340 @@
+
+ 
+
+
+
+ 
+ ·
+ 
+
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+# Looping Marketplace
+
+Marketplace web completo para comprar y vender productos, con pagos online seguros y cuentas de comprador y vendedor.
+
+CRUD completo de productos | Roles de comprador y vendedor | Pagos con Stripe | 2 idiomas (EN / ES)
+
+---
+
+## Tabla de contenidos
+
+- [Descripción del proyecto](#descripción-del-proyecto)
+- [Funcionalidades](#funcionalidades)
+- [Arquitectura](#arquitectura)
+- [Stack técnico](#stack-técnico)
+- [Estructura del proyecto](#estructura-del-proyecto)
+- [Modelo de datos](#modelo-de-datos)
+- [Endpoints de la API](#endpoints-de-la-api)
+- [Puesta en marcha](#puesta-en-marcha)
+ - [Ejecutar con Make (recomendado)](#ejecutar-con-make-recomendado)
+ - [Ejecutar en macOS / Linux](#ejecutar-en-macos--linux)
+ - [Ejecutar en Windows](#ejecutar-en-windows)
+ - [Ejecutar con Docker](#ejecutar-con-docker)
+- [Variables de entorno](#variables-de-entorno)
+- [Comandos de Make](#comandos-de-make)
+- [Hoja de ruta](#hoja-de-ruta)
+- [Contribuir](#contribuir)
+
+---
+
+## Descripción del proyecto
+
+**Looping Marketplace** es una aplicación web completa diseñada para comprar y vender productos. Incluye un sistema CRUD completo e integra Stripe como pasarela de pago.
+
+La aplicación es totalmente funcional para uso real. Los usuarios pueden crear una cuenta y empezar a explorar y comprar productos de inmediato. Para convertirse en vendedor, pagan una cuota única que desbloquea el rol de vendedor y les permite publicar y gestionar sus propios productos.
+
+## Funcionalidades
+
+- Sistema CRUD completo para productos
+- Autenticación de usuarios y gestión de roles (comprador / vendedor)
+- Upgrade único para convertirse en vendedor
+- Integración de pagos con Stripe (checkout individual y múltiple)
+- Favoritos y carrito de compra
+- Almacenamiento de imágenes de producto en Supabase
+- Base de datos PostgreSQL (SQLite como respaldo en desarrollo local)
+- Interfaz responsive construida con Bootstrap
+- Páginas de error personalizadas (400 / 403 / 404 / 500) y logging centralizado
+
+## Arquitectura
+
+Looping Marketplace es un **monolito Django con renderizado en servidor**. Django gestiona la lógica de negocio y el HTML (plantillas Django + Bootstrap); los servicios externos se encargan de los pagos, el almacenamiento de imágenes y la base de datos.
+
+```
+ ┌──────────────────────────────┐
+ Navegador ──────▶│ Django (app MarketPlace) │
+ (UI Bootstrap, │ ────────────────────────── │
+ Stripe.js, │ urls.py → enrutado │
+ SweetAlert2) │ views.py → lógica negocio │
+ │ models.py → ORM │
+ │ templates → HTML servidor │
+ └───────┬───────┬───────┬──────┘
+ │ │ │
+ ┌──────────────┘ │ └──────────────┐
+ ▼ ▼ ▼
+ ┌───────────────┐ ┌────────────────┐ ┌────────────────┐
+ │ PostgreSQL │ │ Stripe │ │ Supabase │
+ │ (Supabase / │ │ Checkout y │ │ Bucket de │
+ │ SQLite local)│ │ pagos │ │ imágenes │
+ └───────────────┘ └────────────────┘ └────────────────┘
+```
+
+**Flujo de una petición**
+
+1. Un usuario se registra / inicia sesión → la autenticación de Django crea la cuenta y una señal `post_save` crea su `UserProfile`.
+2. Un vendedor crea un producto → la imagen se sube al bucket `products_images` de Supabase y su URL pública se guarda en el `Product`.
+3. Un comprador compra → se crea una sesión de Stripe Checkout → Stripe redirige a la URL de éxito → se registra el pedido.
+4. Favoritos y carrito se guardan como relaciones del `UserProfile`.
+
+## Stack técnico
+
+| Capa | Tecnología |
+|------|-----------|
+| Framework web | Django 6.0 (Python 3.12) |
+| Frontend | Plantillas Django + Bootstrap 5.3, Stripe.js, SweetAlert2 |
+| Base de datos | PostgreSQL (vía `dj-database-url`) · SQLite en desarrollo local |
+| Almacenamiento de imágenes | Supabase Storage |
+| Pagos | Stripe Checkout |
+| Autenticación | Autenticación de Django + señales de perfil |
+| Gestor de paquetes | uv |
+| Contenedores | Docker / Docker Compose |
+| Tooling | Make |
+
+## Estructura del proyecto
+
+```
+MarketPlace/
+├── Makefile # Comandos de desarrollo (install, dev, migrate, docker-up...)
+├── README.md / README.es.md # Documentación (EN / ES)
+├── backend/
+│ ├── manage.py # Punto de entrada de la CLI de Django
+│ ├── pyproject.toml # Proyecto uv + dependencias
+│ ├── requirements.txt # Dependencias pip (alternativa)
+│ ├── Dockerfile # Imagen del servidor
+│ ├── docker-compose.yml # Servicio del servidor en el puerto 8000
+│ ├── MarketPlace/ # Paquete del proyecto Django
+│ │ ├── settings.py # Configuración global (apps, BD, Stripe, logging)
+│ │ ├── urls.py # Router raíz (todos los endpoints)
+│ │ ├── views.py # Todas las vistas de la plataforma
+│ │ ├── models.py # Product, UserProfile, Location, Favorite, Order, ShoppingCart
+│ │ ├── forms.py # Formularios Django
+│ │ ├── admin.py # Registro en el admin de Django
+│ │ ├── error_views.py # Handlers 400 / 403 / 404 / 500
+│ │ └── error_handlers.py # Middleware de errores
+│ ├── services/ # Integraciones externas
+│ │ ├── stripe_service.py # Configuración de Stripe
+│ │ └── supabase.py # Cliente de Supabase (almacenamiento de imágenes)
+│ ├── config_logs/ # Configuración centralizada de logging
+│ ├── templates/ # HTML en servidor (main, product_detail, login, profile...)
+│ └── static/ # CSS/JS de Bootstrap e imágenes
+└── frontend/ # Maquetas HTML estáticas (referencia, no conectadas a la app)
+```
+
+## Modelo de datos
+
+| Modelo | Propósito | Relaciones clave |
+|--------|-----------|------------------|
+| `UserProfile` | Extiende el `User` de Django; `is_premium` marca a un vendedor | 1:1 `User`, FK `Location`, M2M `Product` (favoritos) |
+| `Location` | Ciudad / país de un usuario o producto | referenciado por `UserProfile` y `Product` |
+| `Product` | Artículo publicado a la venta | FK `seller` (UserProfile), FK `Location` |
+| `Order` | Compra completada (comprador ≠ vendedor) | FK `buyer`, FK `seller`, FK `product` |
+| `Favorite` | Producto guardado | FK `UserProfile`, FK `Product` (únicos juntos) |
+| `ShoppingCart` | Línea del carrito | FK `UserProfile`, FK `Product` (únicos juntos) |
+
+> Se crea un `UserProfile` automáticamente para cada nuevo `User` mediante una señal `post_save`. Un usuario se convierte en **vendedor** cuando `is_premium = True` (tras el pago de upgrade).
+
+## Endpoints de la API
+
+| Ruta | Nombre | Propósito |
+|------|--------|-----------|
+| `/` | `main_page` | Catálogo de productos |
+| `/product//` | `product_detail` | Página de detalle de producto |
+| `/product/new/` | `create_product` | Crear una publicación |
+| `/product/buy//` | `acquire_product` | Completar una compra |
+| `/product/delete//` | `delete_product` | Eliminar una publicación |
+| `/register/` · `/login/` · `/logout/` | auth | Acceso de cuenta |
+| `/profile/` | `user_profile` | Compras, ventas y favoritos |
+| `/profile/upgrade/` | `upgrade_to_seller` | Convertirse en vendedor |
+| `/favorites/` · `/toggle-favorites//` | favoritos | Gestionar favoritos |
+| `/shopping-cart/` · `/toggle-shopping-cart//` | carrito | Gestionar carrito |
+| `/create-checkout-session//` | `create_checkout_session` | Checkout Stripe individual |
+| `/create-multi-checkout/` | `create_multi_checkout` | Checkout Stripe múltiple |
+| `/create-upgrade-session/` | `create_upgrade_session` | Checkout de upgrade a vendedor |
+| `/about/` · `/contact/` · `/info/` | páginas estáticas | Páginas informativas |
+| `/admin/` | — | Admin de Django |
+
+---
+
+## Puesta en marcha
+
+### Requisitos
+
+- **Python 3.12+**
+- **[uv](https://docs.astral.sh/uv/)** (recomendado) — o pip
+- **Make** (preinstalado en macOS/Linux; en Windows usa WSL o ejecuta los comandos sueltos)
+- **Docker Desktop** (opcional)
+- **Git**
+
+Clona primero el repositorio:
+
+```bash
+git clone https://github.com/Bootcamp-IA-P6/MarketPlace.git
+cd MarketPlace
+```
+
+### Ejecutar con Make (recomendado)
+
+Desde la raíz del proyecto:
+
+```bash
+make dev
+```
+
+Esto instala las dependencias con uv, aplica las migraciones y arranca el servidor en **http://localhost:8000**.
+
+### Ejecutar en macOS / Linux
+
+```bash
+cd backend
+uv sync # crea .venv e instala dependencias
+uv run python manage.py migrate # prepara la base de datos
+uv run python manage.py runserver # arranca en http://localhost:8000
+```
+
+
+Sin uv (venv + pip clásico)
+
+```bash
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py runserver
+```
+
+
+### Ejecutar en Windows
+
+**PowerShell con uv (recomendado):**
+
+```powershell
+cd backend
+uv sync
+uv run python manage.py migrate
+uv run python manage.py runserver
+```
+
+
+Sin uv (venv + pip clásico)
+
+```powershell
+cd backend
+python -m venv venv
+venv\Scripts\activate
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py runserver
+```
+
+
+> `make` no está disponible en Windows por defecto. Usa los comandos de arriba o ejecuta el proyecto dentro de **WSL** para poder usar `make dev`.
+
+### Ejecutar con Docker
+
+Descarga y ejecuta la imagen publicada (sin clonar):
+
+```bash
+docker pull iruperth/looping:latest
+docker run -d -p 8000:8000 iruperth/looping:latest
+```
+
+O constrúyela desde el código con Docker Compose:
+
+```bash
+cd backend
+docker compose up --build # añade -d para ejecutarlo en segundo plano
+docker compose down # detener
+```
+
+---
+
+## Variables de entorno
+
+Crea un archivo `backend/.env`. Para desarrollo local todo tiene un valor por defecto seguro, así que un archivo vacío/mínimo ya funciona (se usa SQLite y los pagos/almacenamiento quedan desactivados).
+
+```env
+# Django
+DJANGO_SECRET_KEY=cambia-esto-en-produccion
+DJANGO_DEBUG=True
+
+# Base de datos — omítela para usar el respaldo SQLite local
+DATABASE_URL=postgresql://user:password@host:5432/marketplace
+
+# Stripe — déjalas vacías para desactivar los pagos reales
+STRIPE_PUBLIC_KEY=pk_test_xxx
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+
+# Supabase — déjalas vacías para desactivar la subida de imágenes
+SUPABASE_URL=https://tu-proyecto.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=tu-service-role-key
+```
+
+| Variable | Obligatoria | Por defecto / efecto |
+|----------|-------------|----------------------|
+| `DJANGO_SECRET_KEY` | En producción | Clave de desarrollo insegura si no se define |
+| `DJANGO_DEBUG` | No | `True` en desarrollo local |
+| `DATABASE_URL` | En producción | SQLite (`db.sqlite3`) si no se define |
+| `STRIPE_PUBLIC_KEY` | Para pagos | Placeholder de test si no se define |
+| `STRIPE_SECRET_KEY` | Para pagos | Vacía → checkout desactivado |
+| `STRIPE_WEBHOOK_SECRET` | Para webhooks | Vacía |
+| `SUPABASE_URL` | Para subir imágenes | Vacía → almacenamiento desactivado |
+| `SUPABASE_SERVICE_ROLE_KEY` | Para subir imágenes | Vacía → almacenamiento desactivado |
+
+## Comandos de Make
+
+```bash
+make help # lista todos los targets disponibles
+make install # crea el entorno virtual e instala dependencias (uv sync)
+make dev # install + migrate + arranca el servidor de desarrollo
+make run # arranca el servidor (sin sync / migrate)
+make migrate # aplica las migraciones de la base de datos
+make makemigrations # genera nuevas migraciones
+make superuser # crea un usuario administrador de Django
+make shell # abre la shell de Django
+make collectstatic # recopila los archivos estáticos
+make test # ejecuta los tests
+make clean # elimina archivos de cache de Python
+make docker-up # docker compose up --build
+make docker-down # docker compose down
+```
+
+## Hoja de ruta
+
+- Chat en tiempo real entre compradores y vendedores
+- Promoción de pago opcional para destacar productos en lo alto del marketplace
+- Cupones de descuento para compradores frecuentes
+- Notificaciones automáticas de pedidos, mensajes de chat y alertas de bajo stock
+- Objetivo a largo plazo: aplicación móvil nativa
+
+## Contribuir
+
+Damos la bienvenida a contribuciones para mejorar Looping Marketplace. Si quieres colaborar, abre un pull request y nuestro equipo lo revisará.
+
+---
+
+
+ 
+
diff --git a/README.md b/README.md
index 87eaa92..f0c3328 100644
--- a/README.md
+++ b/README.md
@@ -1,135 +1,340 @@
+
+
+
-# Looping Marketplace
+
+
+ ·
+
+
-
+
+
+
+
+
+
+
+
+
+# Looping Marketplace
+
+Full web marketplace to buy and sell products, with secure online payments and buyer and seller accounts.
+Full product CRUD | Buyer & seller roles | Stripe payments | 2 languages (EN / ES)
-Looping Marketplace is a full web application designed for buying and selling products. It includes a complete CRUD system and is built using Django, PostgreSQL, Supabase, Python, and Bootstrap for the frontend. The platform also integrates Stripe as a payment gateway.
+---
-The application is fully functional for real use. Users can create an account and start browsing and purchasing products immediately. To become a seller, users must pay a one-time a fee, which unlocks the seller role and allows them to list and manage their own products.
+## Table of contents
+
+- [Project description](#project-description)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Tech stack](#tech-stack)
+- [Project structure](#project-structure)
+- [Data model](#data-model)
+- [API endpoints](#api-endpoints)
+- [Getting started](#getting-started)
+ - [Run with Make (recommended)](#run-with-make-recommended)
+ - [Run on macOS / Linux](#run-on-macos--linux)
+ - [Run on Windows](#run-on-windows)
+ - [Run with Docker](#run-with-docker)
+- [Environment variables](#environment-variables)
+- [Make commands](#make-commands)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+
+---
+
+## Project description
+
+**Looping Marketplace** is a full web application designed for buying and selling products. It ships with a complete CRUD system and integrates Stripe as a payment gateway.
+
+The application is fully functional for real use. Users can create an account and start browsing and purchasing products immediately. To become a seller, users pay a one-time fee that unlocks the seller role and lets them list and manage their own products.
+
+## Features
-## Current Features
- Full CRUD system for products
-- User authentication and role management
-- Buyer and seller account types
-- Stripe payment integration
-- PostgreSQL database with Supabase
+- User authentication and role management (buyer / seller)
+- One-time upgrade to become a seller
+- Stripe payment integration (single and multi-item checkout)
+- Favorites and shopping cart
+- Product image storage on Supabase
+- PostgreSQL database (SQLite fallback for local development)
- Responsive UI built with Bootstrap
-- Marketplace ready for real transactions
+- Custom error pages (400 / 403 / 404 / 500) and centralized logging
-## Future Enhancements
-- Real-time chat between buyers and sellers
-- Optional paid promotion for sellers to highlight products at the top of the marketplace
-- Discount coupons for frequent buyers
-- Automated notifications for:
- - Order updates
- - Chat messages
- - Low stock alerts
-- Long-term goal: native mobile application
+## Architecture
-Looping Marketplace is designed to grow into a complete e-commerce ecosystem with advanced features for both buyers and sellers.
+Looping Marketplace is a **server-side rendered Django monolith**. Django serves both the business logic and the HTML (Django templates + Bootstrap); external services handle payments, image storage and the database.
+```
+ ┌──────────────────────────────┐
+ Browser ───────▶│ Django (MarketPlace app) │
+ (Bootstrap UI, │ ────────────────────────── │
+ Stripe.js, │ urls.py → routing │
+ SweetAlert2) │ views.py → business logic │
+ │ models.py → ORM │
+ │ templates → server-side HTML│
+ └───────┬───────┬───────┬──────┘
+ │ │ │
+ ┌──────────────┘ │ └──────────────┐
+ ▼ ▼ ▼
+ ┌───────────────┐ ┌────────────────┐ ┌────────────────┐
+ │ PostgreSQL │ │ Stripe │ │ Supabase │
+ │ (Supabase / │ │ Checkout & │ │ Storage bucket │
+ │ SQLite local)│ │ payments │ │ product images │
+ └───────────────┘ └────────────────┘ └────────────────┘
+```
+**Request flow**
-#### Comprehensive step-by-step instructions for installing and running the MarketPlace application.
+1. A user registers / logs in → Django auth creates the account, and a `post_save` signal creates the matching `UserProfile`.
+2. A seller creates a product → the image is uploaded to the Supabase `products_images` bucket and its public URL is stored on the `Product`.
+3. A buyer purchases → a Stripe Checkout session is created → Stripe redirects back to a success URL → the order is recorded.
+4. Favorites and cart are stored as relations on `UserProfile`.
-## Requirements.
-- Python 3.12+
-- pip
-- Docker Desktop
-- Git
+## Tech stack
-## Quick Start (Docker).
+| Layer | Technology |
+|-------|-----------|
+| Web framework | Django 6.0 (Python 3.12) |
+| Frontend | Django templates + Bootstrap 5.3, Stripe.js, SweetAlert2 |
+| Database | PostgreSQL (via `dj-database-url`) · SQLite fallback in local dev |
+| Image storage | Supabase Storage |
+| Payments | Stripe Checkout |
+| Auth | Django authentication + profile signals |
+| Package manager | uv |
+| Containerization | Docker / Docker Compose |
+| Tooling | Make |
-Repository.
-[MarketPlace](https://github.com/Bootcamp-IA-P6/MarketPlace)
+## Project structure
-You do not need to clone the repository to run the application:
-```bash
-docker pull iruperth/looping:latest
-docker run -d -p 8000:8000 iruperth/looping:latest
+```
+MarketPlace/
+├── Makefile # Dev commands (install, dev, migrate, docker-up...)
+├── README.md / README.es.md # Documentation (EN / ES)
+├── backend/
+│ ├── manage.py # Django CLI entry point
+│ ├── pyproject.toml # uv project + dependencies
+│ ├── requirements.txt # pip dependencies (alternative)
+│ ├── Dockerfile # Server image
+│ ├── docker-compose.yml # Server service on port 8000
+│ ├── MarketPlace/ # Django project package
+│ │ ├── settings.py # Global config (apps, DB, Stripe, logging)
+│ │ ├── urls.py # Root router (all endpoints)
+│ │ ├── views.py # All platform views
+│ │ ├── models.py # Product, UserProfile, Location, Favorite, Order, ShoppingCart
+│ │ ├── forms.py # Django forms
+│ │ ├── admin.py # Django admin registration
+│ │ ├── error_views.py # 400 / 403 / 404 / 500 handlers
+│ │ └── error_handlers.py # Error middleware
+│ ├── services/ # External integrations
+│ │ ├── stripe_service.py # Stripe configuration
+│ │ └── supabase.py # Supabase client (image storage)
+│ ├── config_logs/ # Centralized logging config
+│ ├── templates/ # Server-side HTML (main, product_detail, login, profile...)
+│ └── static/ # Bootstrap CSS/JS and images
+└── frontend/ # Static HTML mockups (reference, not wired to the app)
```
-If you prefer to clone the repository and run it locally:
+## Data model
+
+| Model | Purpose | Key relations |
+|-------|---------|---------------|
+| `UserProfile` | Extends Django `User`; `is_premium` marks a seller | 1:1 `User`, FK `Location`, M2M `Product` (favorites) |
+| `Location` | City / country of a user or product | referenced by `UserProfile` and `Product` |
+| `Product` | Item listed for sale | FK `seller` (UserProfile), FK `Location` |
+| `Order` | Completed purchase (buyer ≠ seller) | FK `buyer`, FK `seller`, FK `product` |
+| `Favorite` | Saved product | FK `UserProfile`, FK `Product` (unique together) |
+| `ShoppingCart` | Cart line | FK `UserProfile`, FK `Product` (unique together) |
+
+> A `UserProfile` is created automatically for every new `User` via a `post_save` signal. A user becomes a **seller** when `is_premium = True` (set after the upgrade payment).
+
+## API endpoints
+
+| Route | Name | Purpose |
+|-------|------|---------|
+| `/` | `main_page` | Product catalog |
+| `/product//` | `product_detail` | Product detail page |
+| `/product/new/` | `create_product` | Create a listing |
+| `/product/buy//` | `acquire_product` | Complete a purchase |
+| `/product/delete//` | `delete_product` | Remove a listing |
+| `/register/` · `/login/` · `/logout/` | auth | Account access |
+| `/profile/` | `user_profile` | Purchases, sales and favorites |
+| `/profile/upgrade/` | `upgrade_to_seller` | Become a seller |
+| `/favorites/` · `/toggle-favorites//` | favorites | Manage favorites |
+| `/shopping-cart/` · `/toggle-shopping-cart//` | cart | Manage cart |
+| `/create-checkout-session//` | `create_checkout_session` | Single-item Stripe checkout |
+| `/create-multi-checkout/` | `create_multi_checkout` | Multi-item Stripe checkout |
+| `/create-upgrade-session/` | `create_upgrade_session` | Seller upgrade checkout |
+| `/about/` · `/contact/` · `/info/` | static pages | Informational pages |
+| `/admin/` | — | Django admin |
+
+---
+
+## Getting started
+
+### Requirements
+
+- **Python 3.12+**
+- **[uv](https://docs.astral.sh/uv/)** (recommended) — or pip
+- **Make** (preinstalled on macOS/Linux; on Windows use WSL or run the raw commands)
+- **Docker Desktop** (optional)
+- **Git**
+
+Clone the repository first:
-``` bash
+```bash
git clone https://github.com/Bootcamp-IA-P6/MarketPlace.git
-cd MarketPlace/backend
-docker compose up --build
+cd MarketPlace
```
-To run the containers in the background:
+### Run with Make (recommended)
-``` bash
-docker compose up -d
+From the project root:
+
+```bash
+make dev
```
-# Run Locally.
-## Create virtual environment.
+This installs dependencies with uv, applies migrations and starts the server at **http://localhost:8000**.
+### Run on macOS / Linux
-### Mac / Linux
-``` bash
+```bash
cd backend
+uv sync # create .venv and install dependencies
+uv run python manage.py migrate # set up the database
+uv run python manage.py runserver # start at http://localhost:8000
```
-``` bash
+
+Without uv (plain venv + pip)
+
+```bash
+cd backend
python3 -m venv venv
-```
-``` bash
source venv/bin/activate
-```
-### Windows
-``` bash
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py runserver
+```
+
+
+### Run on Windows
+
+**PowerShell with uv (recommended):**
+
+```powershell
cd backend
+uv sync
+uv run python manage.py migrate
+uv run python manage.py runserver
```
-``` bash
+
+
+Without uv (plain venv + pip)
+
+```powershell
+cd backend
python -m venv venv
-```
-``` bash
venv\Scripts\activate
-```
-### Install dependencies.
-``` bash
pip install -r requirements.txt
-```
-### Apply migrations.
-``` bash
python manage.py migrate
-```
-### Run development server.
-``` bash
python manage.py runserver
```
+
+
+> `make` is not available on Windows by default. Use the commands above, or run the project inside **WSL** to use `make dev`.
+
+### Run with Docker
+
+Pull and run the published image (no clone needed):
+
+```bash
+docker pull iruperth/looping:latest
+docker run -d -p 8000:8000 iruperth/looping:latest
+```
+
+Or build from source with Docker Compose:
+
+```bash
+cd backend
+docker compose up --build # add -d to run in the background
+docker compose down # stop
+```
+
+---
+
+## Environment variables
+
+Create a `backend/.env` file. For local development everything has a safe default, so an empty/minimal file already works (SQLite is used and payments/storage are disabled).
+
+```env
+# Django
+DJANGO_SECRET_KEY=change-me-in-production
+DJANGO_DEBUG=True
+
+# Database — omit to use the local SQLite fallback
+DATABASE_URL=postgresql://user:password@host:5432/marketplace
+
+# Stripe — leave empty to disable real payments
+STRIPE_PUBLIC_KEY=pk_test_xxx
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+
+# Supabase — leave empty to disable image uploads
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+```
-# Build and start containers with DOCKER.
-``` bash
-docker compose up --build
-```
-### Run in background.
-``` bash
-docker compose up -d
-```
-### Stop containers.
-``` bash
-docker compose down
-```
+| Variable | Required | Default / effect |
+|----------|----------|------------------|
+| `DJANGO_SECRET_KEY` | Production | Insecure dev key if unset |
+| `DJANGO_DEBUG` | No | `True` in local dev |
+| `DATABASE_URL` | Production | SQLite (`db.sqlite3`) if unset |
+| `STRIPE_PUBLIC_KEY` | For payments | Test placeholder if unset |
+| `STRIPE_SECRET_KEY` | For payments | Empty → checkout disabled |
+| `STRIPE_WEBHOOK_SECRET` | For webhooks | Empty |
+| `SUPABASE_URL` | For image upload | Empty → storage disabled |
+| `SUPABASE_SERVICE_ROLE_KEY` | For image upload | Empty → storage disabled |
+## Make commands
-
-
+```bash
+make help # list all available targets
+make install # create the virtual environment and install dependencies (uv sync)
+make dev # install + migrate + run the development server
+make run # start the server (no sync / migrate)
+make migrate # apply database migrations
+make makemigrations # generate new migrations
+make superuser # create a Django admin user
+make shell # open the Django shell
+make collectstatic # collect static files
+make test # run the test suite
+make clean # remove Python cache files
+make docker-up # docker compose up --build
+make docker-down # docker compose down
+```
+## Roadmap
+
+- Real-time chat between buyers and sellers
+- Optional paid promotion to highlight products at the top of the marketplace
+- Discount coupons for frequent buyers
+- Automated notifications for order updates, chat messages and low-stock alerts
+- Long-term goal: native mobile application
## Contributing
-We welcome contributions to improve Looping Marketplace.
-If you would like to collaborate, please create a pull request and our team will review it.
-Thank you for your interest in the project.
+We welcome contributions to improve Looping Marketplace. If you would like to collaborate, please open a pull request and our team will review it.
+
+---
-