integration: full compose (api+worker+frontend) + README

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