From a54ee064c8fd8a23bca20a236e8da0a390c8744f Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 2 May 2026 17:06:44 -0500 Subject: [PATCH] Upload files to "/" --- STORYBID.md | 349 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 STORYBID.md diff --git a/STORYBID.md b/STORYBID.md new file mode 100644 index 0000000..e177f3e --- /dev/null +++ b/STORYBID.md @@ -0,0 +1,349 @@ +# Charity Auction App Plan + +## Overview + +This plan outlines a self-hosted charity auction platform for a single organization that can run multiple auctions per organization, including both live and silent auctions in the same event. The system is designed to remain operational when internet access is lost by defaulting to a public FQDN when available and automatically failing over to a local IP or custom local DNS hostname on the event Wi-Fi network, which is feasible with UniFi hardware that supports local DNS records and hostnames.[^1][^2][^3] + +The primary goal is to prevent bid loss during live fundraising events by combining offline-first client behavior, local-network failover, and persistent local storage. Service workers, IndexedDB outbox queuing, and reconnection sync patterns are common approaches for resilient offline-first web apps, and Socket.io-style real-time messaging is a practical fit for live auction state updates.[^4][^5][^6][^7] + +## Confirmed Product Decisions + +| Area | Decision | +|---|---| +| Payments | Stripe integration for checkout and invoices[^8][^9] | +| Tenancy | Single organization per install, multiple auctions/events per organization | +| Authentication | Email login plus phone/SMS OTP support using a verification flow such as Twilio Verify[^10][^11] | +| Media | Support all media types for auction items, including images, video, documents, and external embeds; presigned-upload patterns are a strong fit for secure media handling[^12][^13] | +| Networking | Public FQDN first, then local IP or local DNS hostname on event Wi-Fi; UniFi local DNS records support this pattern[^14][^3] | +| Auction Modes | Live auction and silent auction in the same event[^15][^16] | + +## Core Product Scope + +The platform should support one nonprofit or organization per installation, with the ability to create many events and many auctions inside those events. Each event can include live auction lots, silent auction lots, paddle raise campaigns, and general donations, all managed from one admin console and surfaced in a single bidder experience.[^17][^18][^19] + +The bidder experience should be mobile-first and installable as a Progressive Web App so guests can use their phones without downloading an app store package. PWA app-shell caching and local persistent storage are well-suited for event environments with unstable connectivity.[^5][^2][^1] + +## Recommended Feature Set + +### Admin and Event Operations + +- Organization profile and branding settings. +- Multiple events per organization. +- Auction creation with support for live, silent, and hybrid event structures.[^15][^16] +- Item management for title, description, donor, category, value, photos, video, documents, and pickup notes.[^12][^13] +- Bulk bidder import by CSV and manual bidder creation. +- Bidder profiles with contact info, paddle number, table assignment, notes, and payment status. +- User roles for admin, event manager, auctioneer, spotter, check-in staff, and bidder. +- Stripe-backed checkout, card capture, invoices, receipts, and settlement workflows.[^8][^9] +- Audit log with explicit offline-origin flagging for bids synced later. + +### Live Auction Features + +- Auctioneer console for the current lot, current bid, next bid amount, bidder paddle, and recent bid stream. +- Auctioneer-controlled bid increments rather than free-form bidder entry, matching the auctioneer-call format described earlier.[^20][^21] +- Spotter Mode so volunteers can enter bids by paddle number from the floor. +- Display Board for projector or TV with current item, current bid, bidder paddle, branding, and optional fundraising thermometer.[^22] +- Going once / going twice / sold workflow with item lock and winner confirmation. + +### Silent Auction Features + +- Silent auction catalog with item pages, current high bid, minimum next bid, and countdown timer.[^18][^23][^24] +- Configurable closing windows by section, table, or category. +- Optional soft-close / auto-extend behavior to prevent last-second bid sniping, which is a common silent auction pattern.[^25] +- Outbid notifications by push, in-app banner, email, or SMS depending on user settings and available channels.[^26][^27] +- Watchlist / favorites so bidders can track lots they care about. +- Silent-auction bid history visible to admins and optionally summarized for bidders. + +### Fundraising Features + +- Paddle Raise / Fund-a-Need module with donation tiers and live total updates.[^28] +- General donation form for non-auction giving. +- Sponsorship packages and fixed-price “buy now” offers for certain items. +- Post-event winner summary, receipts, and donor acknowledgments. + +### Check-In and Identity Features + +- QR code registration and check-in. +- Digital paddle display on the bidder’s device. +- Email magic link login. +- SMS OTP login for guests who prefer phone-based access, which aligns well with verification workflows like Twilio Verify.[^10][^11] +- Optional payment-method-on-file indicator for faster checkout. + +## User Experience Design + +### Bidder Experience + +Bidders should see a single event app with tabs such as Home, Live, Silent, My Bids, Checkout, and Profile. During the live auction, the app should foreground only the current lot and the next callable bid button; during the silent auction, the app should function more like a real-time catalog with timers, outbid status, and watchlist management.[^21][^18][^26] + +The app should make network state obvious. A persistent connectivity indicator can show whether the device is connected to the public service, the local event server, or temporary offline mode while queued actions await sync.[^29][^2] + +### Staff Experience + +Staff should have separate optimized views for auctioneer, spotter, check-in, and display board roles. This reduces accidental misuse of admin features during the event and keeps each operational screen focused on one task. + +## Technical Architecture + +### Deployment Model + +A single self-hosted installation serves one organization. That installation can run on an on-prem event server, an Unraid host, or a cloud-connected node, with Docker Compose as the default deployment model. During events, the same installation remains reachable at the public FQDN and at a local DNS hostname or local IP on the venue Wi-Fi.[^30][^3] + +### Frontend + +- React + TypeScript. +- Vite-based build. +- PWA installability with service worker. +- IndexedDB via Dexie or idb for offline persistence.[^2][^1] +- Socket.io client for real-time state updates.[^6][^7] + +### Backend + +- Node.js + TypeScript + Express. +- Socket.io server for live channels. +- Prisma ORM. +- PostgreSQL for production, SQLite as a dev or lightweight single-node option. +- Redis optional for queues, rate limiting, and horizontal real-time scaling. + +### Media Storage + +Because the app needs to support all media types, media should be abstracted behind a storage service that can use local disk, S3-compatible storage, or cloud buckets. Presigned-upload patterns are appropriate because they reduce backend load and keep uploads secure.[^13][^12] + +## Offline and Failover Strategy + +The app should treat offline survival as a first-class requirement. The browser caches the application shell and recent event data, then writes bid attempts and critical mutations into a local IndexedDB outbox when requests cannot be completed immediately.[^4][^5][^2] + +The connection manager should attempt the public FQDN first and, if that fails or times out, switch to the configured local DNS hostname or local IP. Since UniFi hardware supports local DNS records and hostnames, a hostname such as `auction.event.lan` or `bid.charity.local` is a better operator experience than exposing raw IP addresses.[^14][^3] + +For live auctions, the safest rule is that the server remains the source of truth for accepted bids while the client remains the source of truth for queued intent. Each queued bid should include bidder ID, item ID, amount, created-at timestamp, client sequence number, and origin mode such as `public`, `local_dns`, `local_ip`, or `offline_queue` so the audit trail can reconstruct exactly what happened. + +## Auction Model Design + +### Live Auction Logic + +Live auction items should move through states such as `preview`, `active`, `going_once`, `going_twice`, `sold`, and `passed`. Bidders should not type custom amounts; instead, they accept the auctioneer-called amount shown in the UI. This reduces user error and keeps phone bids synchronized with the in-room cadence.[^20][^21] + +### Silent Auction Logic + +Silent auction items need a different engine. Each item requires a start time, end time, opening bid, increment rule, current high bid, reserve status, and soft-close behavior. Soft-close or auto-extend can add time if a valid bid lands near closing, reducing last-second sniping and fitting common silent auction practice.[^23][^24][^25] + +### Unified Event Logic + +A single event can contain both live and silent items, but the application should keep their bidding engines separate behind a common item model. This avoids contaminating live-auction rules with silent-auction timing logic while preserving unified reporting, checkout, and bidder identity. + +## Admin Modules + +| Module | Purpose | +|---|---| +| Organization Settings | Branding, Stripe keys, SMS provider config, DNS/failover settings | +| Event Manager | Create events, schedules, auction types, and venue metadata | +| Item Manager | Manage lots, categories, media, donor info, reserves, and increment rules | +| Bidder Manager | Profiles, paddle numbers, QR codes, roles, notes, contact details | +| Check-In | Search, scan, verify, assign paddle, confirm payment readiness | +| Live Control | Auctioneer controls, spotter intake, sold/passed workflow | +| Silent Control | Timer controls, close groups, auto-extend rules, moderation | +| Display Board | TV/projector read-only event view | +| Fund-a-Need | Tier setup, call screen, live totals | +| Checkout | Stripe payment capture, invoices, receipts, settlement | +| Audit Log | Full activity history including offline-origin flags | +| Reporting | Revenue, sell-through, bidder activity, donor and event summaries | + +## Suggested Data Model + +Core entities should include Organization, Event, Auction, AuctionItem, ItemMedia, Bidder, BidderAuthMethod, Bid, SilentAuctionWindow, PaddleRaiseCampaign, Donation, Invoice, Payment, DeviceSession, AuditLog, and Notification. This model supports the confirmed requirements around multiple events, multiple auction modes, all-media support, Stripe checkout, SMS OTP, and bid traceability. + +Important bid fields should include `origin_mode`, `device_id`, `client_created_at`, `server_received_at`, and `sync_status` so offline-origin flagging is easy to report on and operationally defend if disputes occur. + +## API and Real-Time Events + +The API should expose REST endpoints for admin CRUD, bidder authentication, event catalogs, invoices, and media management, while Socket.io handles high-frequency real-time updates for live bidding and silent auction outbid notifications. This split matches common real-time app patterns where stateful event streams complement standard HTTP APIs.[^7][^6] + +Example server events should include `item_activated`, `next_live_bid`, `live_bid_accepted`, `silent_bid_accepted`, `silent_outbid`, `item_sold`, `item_closed`, `paddle_raise_update`, and `sync_status_changed`. These events map directly to the operational screens needed by bidders, spotters, and staff. + +## Authentication and Security + +Bidder authentication should support email magic link and SMS OTP, while admins and staff should use stronger account-based authentication with role checks. Twilio Verify-style flows are a reasonable implementation pattern for SMS verification, and verification best practices emphasize throttling, retry control, and careful code handling.[^11][^10] + +Security controls should include role-based authorization, server-side bid validation, rate limiting on bid submissions, signed media uploads, PCI-safe delegation of payment entry to Stripe, encrypted secrets management, and append-only audit logging for sensitive actions.[^9][^8] + +## Payments and Checkout + +Stripe should handle payment intents, saved payment methods where appropriate, invoices or receipts, and post-event settlement. Using Stripe-hosted or Stripe Elements-based flows avoids storing raw card data in the auction app and reduces PCI scope.[^8][^9] + +Checkout should support these paths: +- Winning bidder pays all won lots after the event. +- Staff-assisted checkout at a cashier station. +- Immediate pay-now for fixed-price offers and optional donations. +- Partial settlement tracking if a bidder pays in person later. + +## Notifications + +Notifications should be channel-aware: +- In-app banners for immediate state updates. +- Web push where supported. +- Email for confirmations and receipts. +- SMS for OTP and optional critical alerts such as outbid or checkout-ready status.[^27][^26] + +Silent auction outbid alerts are especially important because they drive repeat engagement before closing. Live auctions rely more on the real-time on-screen state, but push or sound cues can still improve usability.[^26] + +## Event-Night Network Design + +Use a dedicated UniFi SSID for the event and a local DNS record that resolves the app hostname to the on-site server. Devices join the event Wi-Fi, open the public URL or scan the QR code, and the app can transparently fail over to the internal hostname if the internet path degrades.[^3][^14] + +The local event server should remain physically on the same LAN as the access points and router, with a battery backup if possible. If the WAN drops, local traffic should still move between bidder devices and the server normally, preserving live and silent bidding on the local network. + +## Recommended Build Roadmap + +### Phase 1: Foundation +- Set up monorepo and Docker deployment. +- Implement Organization, Event, Bidder, and Item models. +- Build admin shell and authentication. +- Add Stripe configuration storage. +- Add UniFi/local DNS-aware endpoint configuration. + +### Phase 2: Live Auction Core +- Build auctioneer console. +- Build bidder live-auction screen. +- Implement live increment engine. +- Add Spotter Mode. +- Add Display Board. + +### Phase 3: Silent Auction Core +- Build silent auction catalog and item pages. +- Add countdown timers and close scheduling.[^24][^23] +- Implement bid validation, outbid notifications, and optional auto-extend.[^25][^26] +- Add watchlists and bidder history. + +### Phase 4: Offline Resilience +- Add service worker and PWA shell. +- Add IndexedDB outbox queue. +- Implement endpoint failover from FQDN to local DNS/IP.[^1][^2][^3] +- Add sync engine and audit log origin tagging. +- Simulate internet-drop scenarios during live and silent bidding. + +### Phase 5: Event Ops and Checkout +- Build QR code registration and check-in. +- Add digital paddle display. +- Add Fund-a-Need / Paddle Raise module.[^28] +- Implement Stripe checkout flows and receipts.[^9][^8] +- Add end-of-event reporting and settlements. + +### Phase 6: Hardening and Polish +- Load test with realistic bidder counts. +- Improve accessibility for low-light and high-noise event environments. +- Add backups, export tools, and recovery procedures. +- Finalize README, deployment guide, operator manual, and event-day checklist. + +## Recommended MVP + +The fastest useful MVP should include: +- Single organization install. +- Multiple events. +- Live auction with auctioneer-controlled increments. +- Silent auction with timers and outbid alerts. +- Spotter Mode. +- Display Board. +- QR code check-in and digital paddles. +- Stripe checkout. +- Email login and SMS OTP. +- PWA offline shell plus local DNS failover. +- Audit log with offline-origin flagging. + +This MVP already delivers the critical differentiator: the event can continue on local Wi‑Fi if the public internet becomes unstable, while still supporting both live and silent formats in one system.[^2][^3][^1] + +## Recommended Stack + +| Layer | Recommendation | Reason | +|---|---|---| +| Client | React + TypeScript + Vite | Fast, typed, PWA-friendly | +| UI | Tailwind + component library | Rapid event-optimized UI development | +| Offline | Workbox + IndexedDB | Proven offline-first web patterns[^4][^5] | +| Real-Time | Socket.io | Strong fit for bid events and reconnect handling[^6][^7] | +| API | Node.js + Express + TypeScript | Matches the broader architecture and integration needs | +| ORM | Prisma | Strong TypeScript ergonomics | +| DB | PostgreSQL | Better for production concurrency and reporting | +| Cache/Queue | Redis | Optional for scale and event fan-out | +| Auth | Magic links + Twilio Verify SMS OTP | Low-friction bidder login[^10][^11] | +| Payments | Stripe Payment Element / Payment Intents | Reduced PCI burden[^8][^9] | +| Storage | S3-compatible media storage | Flexible all-media support[^12][^13] | +| Deployment | Docker Compose on Unraid or Linux VM | Fits self-hosted event operations | + +## Implementation Notes + +Given your background, the cleanest implementation path is a monorepo with separate client and server apps, shared TypeScript types, Prisma-managed schema, and a deployment profile that can run identically on Unraid in dev, staging, and event production. The most important engineering discipline for this project is deterministic event logging and failure testing, because trust in the bid history matters as much as feature completeness. + +A good repo structure would include a root README, an `/ops` directory for deployment and network guidance, and an `/event-runbook` directory for staff instructions and preflight checks. That will fit your documentation-first workflow and make the app usable by non-technical event staff. + +## Next Build Step + +The best next step is to turn this plan into a full technical specification with: +1. Prisma schema. +2. Route map and socket event contracts. +3. Role matrix. +4. UI wireframes for admin, auctioneer, bidder, spotter, silent auction, and display board. +5. Docker Compose and UniFi event-network deployment guide. + +That would be the right handoff artifact before scaffolding the actual codebase. + +--- + +## References + +1. [Preparation Tips](https://wild.codes/candidate-toolkit-question/how-would-you-architect-a-pwa-for-offline-first-and-real-time-sync) - Build a production-grade PWA architecture that combines offline-first UX, robust caching strategies,... + +2. [Build Offline-First PWA with Next.js & IndexedDB - WellAlly](https://www.wellally.tech/blog/build-offline-first-pwa-nextjs-indexeddb) - Complete guide to building offline-capable PWAs with Next.js App Router and IndexedDB. Includes serv... + +3. [UniFi DNS Records and Local Hostnames](https://help.ui.com/hc/en-us/articles/15179064940439-UniFi-DNS-Records-and-Local-Hostnames) - Find help and support for Ubiquiti products, view online documentation and get the latest downloads. + +4. [Service Workers: Offline-First Web Applications - Library](https://www.grizzlypeaksoftware.com/library/service-workers-offline-first-web-applications-eu7ftssc) - A comprehensive guide to building offline-first web applications with service workers covering cachi... + +5. [How to Implement Service Workers for Offline Support in React](https://oneuptime.com/blog/post/2026-01-15-service-workers-offline-support-react/view) - Learn how to implement service workers in React applications to enable offline support, improve perf... + +6. [Building a real-time bidding system with Socket.io and ...](https://dev.to/novu/building-a-real-time-bidding-system-with-socketio-and-react-native-1cj5) - What is this article about? Goin’ Once, Goin’ Twice, Sold to the lady with the red dress... + +7. [Building a real-time bidding system with Socket.io and React Native](https://novu.co/blog/building-a-real-time-bidding-system-with-socket-io-and-react-native/) - Here, I will guide you through creating the Socket.io Node.js server for real-time communication wit... + +8. [Build an advanced integration with Node.js - Stripe Documentation](https://docs.stripe.com/payments/quickstart?client=react&lang=node) - Learn how to embed a custom Stripe payment form in your website or application. Build a checkout for... + +9. [Stripe Payment Element](https://docs.stripe.com/payments/payment-element) + +10. [Node.js Authentication With Twilio Verify - Smashing Magazine](https://www.smashingmagazine.com/2022/10/nodejs-authentication-twilio-verify/) - You will build an express application that authenticates users using traditional password-based auth... + +11. [Verification and two-factor authentication best practices - Twilio](https://www.twilio.com/docs/verify/developer-best-practices) - Developer best practices for phone and user verification with SMS, voice, email, WhatsApp, TOTP and ... + +12. [AWS S3 Pre-Signed URLs: Your Key to Secure Media Uploads](https://dev.to/ehsaantech/aws-s3-pre-signed-urls-your-key-to-secure-media-uploads-35kl) - In this article, we'll discuss what pre-signed URLs are, why they're beneficial for uploading media ... + +13. [Uploading objects with presigned URLs - AWS Documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) - You may use presigned URLs to allow someone to upload an object to your Amazon S3 bucket. Using a pr... + +14. [UniFi Local & Server DNS Settings Explained - LazyAdmin](https://lazyadmin.nl/home-network/unifi-local-and-server-dns-settings/) - How to configure DNS Server settings, and add local DNS entries in UniFi Network. Everything you nee... + +15. [Should I Choose a Live Auction or Silent Auction? - Fundraising Blog](https://www.galabid.com/global-fundraising-blog/live-auction-or-silent-auction) - Silent auctions cater to a broader audience, provide flexibility, and can be efficiently managed thr... + +16. [Silent Auction vs Live Auction: Which One is Better for My Nonprofit?](https://www.silentauctionpro.com/blogs/silent-auctions-vs-live-auctions.php) - Unlike silent auctions, live auctions provide instant feedback and gratification. Winners know immed... + +17. [Bid for a Cause: Charity Auction Strategies - Zeffy](https://www.zeffy.com/blog/charity-auction) - Whether you're hosting an online, live, or silent auction, setting up the auction space (or platform... + +18. [Silent Auction Platform | Raise More at Your Event - GalaBid](https://www.galabid.com/silent-auction-global) - Showcase top bids, countdowns, and goals in real time on big screens to energize the room and drive ... + +19. [Best Auction Software for Nonprofits 2026: Complete Buyer's Guide](https://momentivesoftware.com/blog/auction-software/) - The best silent auction software includes features ... Live auctions feature an auctioneer leading t... + +20. [Run a Live Auction (Virtual, Hybrid or In-person)](https://kb.betterunite.com/runaliveauctionvirtualhybridorinperson) - Click Add Item to add a Live Auction Item. · Planned Bid Increments will give the Auctioneer the abi... + +21. [Understand: Auction Bidding Styles | Givebacks Help Center](https://support.givebacks.com/en/articles/11184912-understand-auction-bidding-styles) - English-Style Auctions encourage real-time bidder engagement and competition, driving up the item's ... + +22. [CharityAuctions - Charity Auction Software Features](https://charityauctions.com/features) - Everything included to run a charity auction · Mobile bidding (no app) · Online silent auctions · Li... + +23. [Adding a Countdown Clock to Your Auction Page](https://support.cbo.io/-adding-a-countdown-clock-to-your-auction-page) - To show a countdown clock directly on your auction page for online bidders, follow these steps: Go t... + +24. [Showing Count-Down Timers - Silent Auction Pro](https://www.silentauctionpro.com/help/countdown.php) - Silent Auction Pro provides simple HTML-based count-down timers that you can project at your event. + +25. [What is Auto-Extend/Soft Close During an Online Auction?](https://www.targetauction.com/blog/detail/what-is-auto-extend-soft-close-of-an-online-auction) - The auctioneer has set the bidding to auto-extend if any bids are made within the last two minutes. ... + +26. [How to configure bidder notifications for auctions](https://help.givebutter.com/en/articles/6483895-how-to-configure-bidder-notifications-for-auctions) - Use our automated email and SMS notifications to keep bidders engaged and invested, and see examples... + +27. [Do the auction bidders get a text message when they are outbid?](https://kb.betterunite.com/dotheauctionbiddersgetatextmessagewhentheyareoutbid) - Silent auction bidders do get a notification when they are outbid, provided they entered their phone... + +28. [Set Up The Bidding Paddle Raise Feature | CharityAuctionsToday](https://blog.charityauctionstoday.com/p/help/setting-up-the-paddle-raise-feature/) - To set up a Mobile Paddle, you must first enter six quick donation amounts. Then choose if you would... + +29. [Offline Support and Progressive Web Apps (PWAs)](https://dev.to/zeeshanali0704/frontend-system-design-offline-support-and-progressive-web-apps-pwas-4k8m) - Offline Support and Progressive Web Apps (PWAs) A Complete Frontend System Design... + +30. [Givi - Mobile Giving - Apps on Google Play](https://play.google.com/store/apps/details?id=com.qgiv.givi&hl=en_US) - From browsing and bidding on silent auction items to purchasing event items or giving to live fundra... +