Aurrin Ventures Platform

Context: The brief says “managed database such as PostgreSQL via Supabase or similar.”

Decision: Supabase.

Rationale: Includes auth, realtime, storage, and row-level security out of the box. Reduces the number of services to integrate. Aurrin’s team (non-technical operators) benefits from the Supabase dashboard for direct data inspection when needed.

Trade-offs: Vendor coupling to Supabase. Auth and realtime are good but not infinitely flexible. Acceptable for this scale.

Context: Six user roles with route-level and data-level access control, and some people may wear more than one hat at the same time.

Decision: Use Supabase Auth for authentication, but store role assignments and scopes in relational tables. JWT claims identify the user and can cache coarse context; RLS resolves effective permissions from the database.

Rationale: This supports concurrent roles, event-scoped permissions, auditable admin reassignment, and safer long-term evolution than treating auth metadata as the source of truth.

Trade-offs: More schema and policy complexity up front. Permission changes need careful cache invalidation / token refresh handling.

Context: The brief lists five revenue models: premium subscriptions, digital map purchases, sponsored placements, job board listings, and paid founder upgrades. Each needs its own Stripe logic, admin UI, and access control.

Decision: Build a shared commerce foundation (products, prices, orders, transactions, entitlements) from day one, but activate premium subscriptions first. Additional revenue models reuse the same ledger and entitlement model.

Rationale: This avoids rebuilding access control, reconciliation, exports, and admin tooling every time a new monetization path ships.

Trade-offs: More upfront schema than a subscription-only MVP. Worth it to avoid payment-model rework later.

Context: Admin needs to define scoring categories, weights, scales, and custom questions—cloneable across events. The system also needs analytics, exports, and auditability when rubrics change.

Decision: Store rubric definitions in versioned relational tables. Use JSON only for flexible presentation metadata. When an event goes Live, it binds to an immutable rubric_version. Scores are recorded as normalized responses with calculated aggregate snapshots.

Rationale: This is more analytics-friendly, migration-safe, and auditable than an opaque JSONB-only schema while still supporting dynamic rendering in the scoring UI.

Trade-offs: More tables and joins than a single schema column. Worth it for long-term reporting and change control.

Context: The brief mentions WebSockets for real-time scoring and audience validation. Live UX matters, but correctness cannot depend on a socket staying open.

Decision: All writes go through transactional database endpoints with optimistic concurrency and idempotency keys. Supabase Realtime broadcasts committed changes to subscribed clients. Polling is a fallback display strategy, not the correctness model.

Rationale: This gives the UI a real-time feel without making delivery dependent on ephemeral connection state. Correctness stays in Postgres.

Trade-offs: Slightly more plumbing than naive socket-first updates. Worth it because data integrity survives reconnects and transient outages.

Context: Audience members scan a QR code and submit validation feedback. The brief requires optional anonymous submissions and duplicate prevention.

Decision: Public /validate/[eventId] route. The server issues an audience_session and signed cookie/token on entry. Dedup is enforced with unique constraints plus optional email matching and rate limits. Fingerprinting, if used at all, is only secondary abuse detection.

Rationale: Server-controlled session identity is more reliable, more privacy-conscious, and easier to reason about under GDPR than browser fingerprinting as a primary control.

Trade-offs: Slightly more bootstrap complexity and device-cookie handling. Still the right trade-off for trustworthy validation data.

Context: Emails, PDFs, social assets, mentor matching, Stripe webhooks, and exports should not rely on the request/response lifecycle, especially on Vercel.

Decision: Persist domain events to an outbox table and process them with a dedicated worker/queue. All jobs are idempotent, retryable, and dead-lettered for operator intervention when necessary.

Rationale: Durable jobs survive retries, deploys, and live-event traffic spikes. They also give operators a single place to inspect side-effect failures.

Trade-offs: Introduces worker infrastructure and more operational surface area. Necessary for production-grade reliability.

Context: The brief lists both SendGrid for email and Twilio for SMS as required integrations.

Decision: Use Resend for email (simpler API, fewer integrations to manage). Defer SMS (Twilio) to post-Phase 1. Email covers all critical notifications.

Rationale: SMS adds cost per message and a separate integration to maintain. Every notification in the brief can be delivered via email. SMS can be layered in later for time-sensitive alerts (live event start) once the core platform is stable.

Trade-offs: No SMS for launch. Email delivery is subject to spam filters. Acceptable trade-off—reduces integration surface area for the initial build.

Context: Live events, approvals, score changes, and billing entitlements are the highest-risk moments. They need explicit resilience and audit rules.

Decision: Use optimistic local scoring drafts, idempotent submission APIs, explicit scoring lock/publish states, immutable audit logs for approvals and entitlement changes, and operator-visible failure states for jobs and integrations.

Rationale: A network blip should not lose scores, and a human operator should always be able to explain who changed what and when.

Trade-offs: More state machines, retry logic, and audit volume. Worth it for correctness under pressure.

Context: Founders need downloadable validation reports, and the platform also needs generated social assets and reusable exports.

Decision: Use @react-pdf/renderer and @vercel/og, but generate artifacts asynchronously in the worker tier, store them in object storage, and serve them via signed URLs. API routes request generation or fetch existing artifacts; they do not render heavy outputs inline.

Rationale: This avoids request timeouts and makes artifacts cacheable, retryable, and auditable.

Trade-offs: Eventual consistency: newly requested artifacts may take seconds to appear. Acceptable for reports and share assets.