66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# 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
|