Skip to content

Bid Wars — Documentation

Welcome to the Bid Wars documentation set. Bid Wars is a real-time auction marketplace for creator ad inventory: streamers list ad spots, advertisers bid on them live, and the winning ad serves into the streamer's OBS automatically. Creators keep 85%; the platform takes 15%.

🚀 Live hosted demo: https://demo.bidwars.live — always on, nothing to install, with test data and Stripe test payments. Log in as mira@bidwars.test / demo1234. Full walkthrough in the Demo Playbook.

📖 Browse these docs: https://smooth.bidwars.live — the same documentation, rendered and searchable, with a built-in AI assistant (the "Ask AI" button) that answers questions grounded in these docs.

📄 One-page quickstart (PDF): https://smooth.bidwars.live/quickstart.pdf — print it and keep it next to you during a demo.

Start here

If you are… Read
Lambert — running a demo Demo & Interface Playbook — get it running in 6 commands, demo logins, a 10–15 min talk track, reset & troubleshooting.
Lambert — selling it Marketing & Sales Playbook — mission, positioning, value props, objection handling, pitch copy.
A creator / streamer Creator Guide — list ad spaces, set up the OBS widget, approve bids, get paid.
An advertiser / brand Advertiser Guide — fund, build campaigns, bid live, auto-bid, RFPs, analytics.
A developer / operator Technical Reference — architecture, data model, auction engine, API, deployment, security.

The documents

  1. Technical Reference — Exhaustive engineering doc: stack, repo layout, full data model, the auction engine + fund-hold accounting, real-time layer, OBS widget, REST API, configuration, deployment, mobile clients, security posture, glossary.
  2. Creator Guide — End-to-end guide for creators: profile, ad spaces, OBS setup, receiving/approving bids, scheduling, invites, earnings, bid requests.
  3. Advertiser Guide — End-to-end guide for advertisers: funding & balance, creatives, the campaign wizard, live bidding, buy-now, auto-bid, bid requests, analytics.
  4. Lambert's Demo & Interface Playbook — Operational runbook for standing up and driving a demo with seeded + populated demo data.
  5. Lambert's Marketing & Sales Playbook — Positioning, mission, audience value props, objection handling, and ready-to-use pitch copy.

Platform at a glance

  • Model: two-sided auction marketplace. Every account can switch between creator and advertiser modes.
  • Auction features: live bidding (WebSocket), auto-bid, anti-snipe extension, buy-now, queued listings, and bid requests (RFPs / reverse auctions).
  • Money: advertisers pre-fund via Stripe; funds are held on a bid and refunded automatically if outbid; winning bids pay out 85% creator / 15% platform; every action is audit-logged (SHA-256 hash chain).
  • Ad serving: an OBS browser-source widget (/w/<token>/) shows the winning creative; impressions are focus-tracked.
  • Stack: Django 5.1 · Channels/Daphne (ASGI) · PostgreSQL/Redis (prod) or SQLite/in-memory (dev) · HTMX + Tailwind + Geist · Stripe · DRF + OpenAPI · native iOS & Android clients.
  • Brand: red/white, Geist typeface, primary #E11D2E.

Run a local demo (the short version)

python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export DJANGO_SETTINGS_MODULE=bidwars.settings.dev   # ← required for local/demo
python manage.py migrate
python manage.py seed_demo
python manage.py runserver

Open http://127.0.0.1:8000/ and log in as mira@bidwars.test / demo1234. Full details, demo logins, a "make it look busy" populate script, and a talk track are in the Demo Playbook.

Source-of-truth notes

  • These docs describe the code as it exists in the repository. Where a feature is partially built, it's flagged (see the "What's real vs. roadmap" section in the Demo Playbook §10).
  • Other in-repo references: top-level README.md (quickstart + API map + deploy), DESIGN_HANDOFF.md (product/UX spec), and the .audit/ folder (SECURITY_AUDIT.md, KNOWN_ISSUES.md, DESIGN_AUDIT.md).
  • No application code was modified to produce this documentation. The demo "populate" script in the Demo Playbook is demo-data tooling you run yourself, not a change to Bid Wars.