# 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