Scaffold and Phase 1

2026-05-02 19:46:42 -05:00
parent ab74e7cad4
commit d909cb7c30
92 changed files with 4967 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Storybid
+
+Self-hosted charity auction platform supporting live and silent auctions in the
+same event, with offline-first PWA bidding and automatic LAN failover for
+event-night resilience.
+
+## Stack
+
+| Layer      | Choice                                      |
+|------------|---------------------------------------------|
+| Client     | React 18 + TypeScript + Vite + Tailwind     |
+| PWA/Offline| Workbox (vite-plugin-pwa) + Dexie/IndexedDB |
+| Real-time  | Socket.io                                   |
+| Server     | Node.js + Express + TypeScript              |
+| ORM        | Prisma                                      |
+| Database   | PostgreSQL (SQLite optional for dev)        |
+| Cache/Queue| Redis (optional)                            |
+| Auth       | Email magic links + Twilio Verify SMS OTP   |
+| Payments   | Stripe Payment Element / Payment Intents    |
+| Media      | S3-compatible presigned uploads             |
+| Deploy     | Docker Compose (Unraid / Linux VM)          |
+
+## Quick Start (development)
+
+```bash
+# 1. Clone and install
+git clone <repo>
+cd storybid
+npm install
+
+# 2. Start DB + Redis
+docker compose -f docker-compose.dev.yml up -d
+
+# 3. Configure environment
+cp .env.example .env
+# Edit .env with your Stripe, Twilio, SMTP, and storage keys
+
+# 4. Migrate database and seed demo data
+npm run db:migrate
+npm run db:seed
+
+# 5. Start dev servers
+npm run dev
+# Client → http://localhost:5173
+# Server → http://localhost:3001
+```
+
+## Production Deployment
+
+See [`ops/README.md`](./ops/README.md).
+
+## Event-Night Network
+
+See [`ops/unifi-dns.md`](./ops/unifi-dns.md) for UniFi local DNS setup and
+WAN-failover testing.
+
+## Staff Runbook
+
+See [`event-runbook/preflight.md`](./event-runbook/preflight.md) for the
+pre-event checklist and [`event-runbook/staff-roles.md`](./event-runbook/staff-roles.md)
+for per-role instructions.
+
+## Project Plan
+
+The full product specification lives in [`STORYBID.md`](./STORYBID.md).
+
+## Build Roadmap
+
+| Phase | Focus                                          | Status  |
+|-------|------------------------------------------------|---------|
+| 1     | Foundation – monorepo, auth, org/event models  | 🏗 scaffold |
+| 2     | Live Auction – auctioneer console, bidder view | ⬜ todo |
+| 3     | Silent Auction – catalog, timers, outbid       | ⬜ todo |
+| 4     | Offline Resilience – PWA, outbox, failover     | ⬜ todo |
+| 5     | Event Ops – check-in, checkout, fund-a-need    | ⬜ todo |
+| 6     | Hardening – load test, a11y, backups, docs     | ⬜ todo |