diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4352005
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# Polaris — Automated Commerce Engine
+
+An automated e-commerce/reseller platform: find products → source from authorized
+suppliers → generate original listings → price for profit → auto-route orders →
+sync tracking → measure profit.
+
+**Phase 1 MVP** — one supplier integration, pricing engine, inventory sync, order
+routing, storefront + admin dashboard, first automated order proven end-to-end.
+
+## Stack
+- **Backend** FastAPI (Python 3.12) + SQLAlchemy 2.0 + Pydantic v2
+- **DB** PostgreSQL 16 · **Queue** Celery + Redis 7
+- **Frontend** React 18 + Vite + TypeScript + Tailwind (storefront `/` + admin `/admin`)
+- **Deploy** Docker Compose (self-hosted on Proxmox CT 755 @ 10.30.20.100)
+
+## Quick start
+```bash
+cp .env.example .env          # set POSTGRES_PASSWORD, SECRET_KEY, ADMIN_PASSWORD
+docker compose up -d --build  # postgres + redis + api + worker + frontend
+# seed sample catalog (optional, idempotent):
+docker compose exec api python scripts/seed.py
+```
+- Storefront: `http://<host>/`
+- Admin: `http://<host>/admin`  (login: ADMIN_EMAIL / ADMIN_PASSWORD)
+- API docs: `http://<host>/api/docs` · health: `/api/health`
+
+## Services (compose)
+`postgres` :5432 · `redis` :6379 · `api` :8000 (internal) · `worker` (celery+beat) · `frontend` :80
+
+## Env vars (`.env`)
+| Var | Purpose |
+|---|---|
+| `POSTGRES_PASSWORD` | DB password |
+| `SECRET_KEY` | JWT signing secret |
+| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | admin dashboard login |
+| `DATABASE_URL` / `REDIS_URL` | auto-set by compose; override for external infra |
+
+## Architecture
+```
+ADMIN DASHBOARD / STOREFRONT (React) ──▶ CORE API (FastAPI)
+   ├─ PRODUCT ENGINE (import/normalize/validate)
+   ├─ PRICING ENGINE  (price_rules markup + net-profit)
+   ├─ ORDER ENGINE    (supplier scoring + routing + profit)
+   ├─ SUPPLIER ENGINE (adapter framework: base/csv/sample)
+   └─ INVENTORY SYNC  (Celery beat, every 5 min)
+                 └─▶ PostgreSQL ◀─▶ Analytics / Reporting
+```
+
+## Supplier adapters
+Plug in any source via `app/engines/suppliers/base.py` `SupplierAdapter` interface:
+`get_products / get_inventory / get_price / create_order / get_order_status / get_tracking / cancel_order`.
+Included: `csv_adapter` (CSV feed) + `sample` (seeded test catalog).
+
+## Phases
+1. **MVP** (this) — one supplier, first automated order ✅
+2. **Automation** — auto supplier ordering, tracking sync, price monitoring, supplier scoring, alerts
+3. **Scale** — multiple suppliers + failover, dynamic pricing, opportunity scoring, lifecycle
+4. **Product** — multi-tenant SaaS for other merchants
+
+## Safety / compliance
+- Never auto-publish invalid products (importer validates; invalid items audit-logged)
+- Never sell below configured minimum margin
+- Original content only — never copy supplier/manufacturer branding or copy
+- No raw card storage — payments via a legitimate processor (BTCPay/Stripe) in Phase 2
+- Secrets via env only
diff --git a/docker-compose.yml b/docker-compose.yml
index e15c660..5e57442 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -26,5 +26,44 @@ services:
       timeout: 3s
       retries: 10
 
+  api:
+    build: ./backend
+    environment:
+      DATABASE_URL: postgresql+psycopg2://reseller:${POSTGRES_PASSWORD}@postgres:5432/reseller
+      REDIS_URL: redis://redis:6379/0
+      SECRET_KEY: ${SECRET_KEY:-polaris-dev-secret-change-me}
+      ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@polaris.local}
+      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-changeme}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    expose:
+      - "8000"
+    restart: unless-stopped
+
+  worker:
+    build: ./backend
+    command: celery -A app.tasks.celery_app worker --loglevel=info -B
+    environment:
+      DATABASE_URL: postgresql+psycopg2://reseller:${POSTGRES_PASSWORD}@postgres:5432/reseller
+      REDIS_URL: redis://redis:6379/0
+      SECRET_KEY: ${SECRET_KEY:-polaris-dev-secret-change-me}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  frontend:
+    build: ./frontend
+    ports:
+      - "80:80"
+    depends_on:
+      - api
+    restart: unless-stopped
+
 volumes:
   pgdata: