reseller-platform/backend/README.md

Polaris Backend

FastAPI + SQLAlchemy 2.0 + Pydantic v2 + Celery/Redis backend for the Polaris reseller platform. PostgreSQL schema is canonical in /opt/polaris/db/schema.sql (not managed by this service).

Run (CT host, no Docker)

cd /opt/polaris/backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
# .env at /opt/polaris/.env provides POSTGRES_PASSWORD (auto-loaded)
.venv/bin/python scripts/seed.py                      # sample supplier + 27 products
DATABASE_URL=postgresql+psycopg2://reseller:${POSTGRES_PASSWORD}@127.0.0.1:5432/reseller \
  .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000

Run (Docker, via OPS compose)

The OPS agent adds api + worker services. Inside the Docker network:

• DATABASE_URL=postgresql+psycopg2://reseller:${POSTGRES_PASSWORD}@postgres:5432/reseller
• REDIS_URL=redis://redis:6379/0
• worker command: scripts/celery_worker.sh (worker + beat; beat schedule in app/tasks.py)

Env vars

var	purpose
DATABASE_URL	SQLAlchemy URL (default: local 127.0.0.1:5432 w/ POSTGRES_PASSWORD)
REDIS_URL	Celery broker (default redis://redis:6379/0)
SECRET_KEY	JWT signing key (dev default — set in prod)
ADMIN_EMAIL / ADMIN_PASSWORD	admin login (plain compare — TODO: hash ADMIN_PASSWORD_HASH with bcrypt/argon2)

API

All under /api (see CONTRACT.md for the full list). Interactive docs at /docs.

Key notes:

• Importer NEVER auto-publishes: new products enter as status='imported'; POST /api/products/{id}/publish requires a calculated retail_price.
• Pricing: active price_rules bands (cost → markup), floor at cost+shipping+fees, min_price respected; estimate_net_profit = retail − cost − shipping − fees.
• Orders: POST /api/orders routes each item to the highest-scoring eligible supplier (40% price / 20% inventory / 15% speed / 10% fulfillment / 10% returns / 5% history) and records profit.
• Analytics conversion is 0.0 until a traffic/visitor source exists.

Seed

scripts/seed.py — idempotent. Creates the sample supplier, imports 27 products (home/gadgets/office, $50–$500 retail), prices via the pricing engine, and publishes the valid ones.