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

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