Building Imperial Votes: A Multi-Tenant Next.js & Prisma Competition Operating System

Imperial Votes Case Study | Next.js SaaS Voting Platform, Branding, Payments, Leaderboard Graphics#

Project Context#

Imperial Votes needed to be a platform that competition organizers could actually run their events on.

A simple contestant listing and voting page would not be enough. Organizers needed to create and manage competitions, upload contestants, define vote bundles, collect paid votes, review contestant applications, configure branding, manage sponsors, export data, understand revenue, and communicate with contestants and voters. Super admins needed platform-wide visibility, tenant management, settings, membership pricing, payout review, role control, audit logs, and support tooling.

The public side also needed to feel trustworthy. Voters needed clean competition pages, contestant profiles, vote checkout, payment confirmation, public leaderboards, share flows, sponsor placements, and branded visuals. Contestants needed signup, login, application forms, file uploads, application tracking, profile management, reviews, and gallery management.

The project evolved from the basic "contestant plus competition plus voting" idea into a multi-role SaaS product.

The Problem#

The main challenge was not only building voting. The harder problem was building a platform where voting, money, permissions, content, branding, and operations all agree with each other.

Voting platforms have several sensitive edges:

• Votes must not be duplicated when a webhook retries.
• Revenue must be calculated from money paid, not from promotional vote bonuses.
• Failed, abandoned, processing, refunded, and completed orders need distinct states.
• Organizers must only see and edit their own competitions.
• Team members need permission-based access, not blanket admin access.
• Public leaderboards and generated graphics must use the same ranking source.
• Competition branding must be flexible without breaking accessibility.
• Contestant applications must handle media, documents, fees, review states, and notifications.
• Judging must support rounds, criteria, weights, scorecards, and auditability.
• Reports must match the ledger, not whatever the UI happens to show.

Treating the project as an end-to-end platform build was essential to resolve these requirements cleanly.

My Role#

I worked as the full-stack developer responsible for turning the idea into a working product.

My role covered:

• Product architecture
• Database modeling with Prisma and PostgreSQL
• API design and backend service layers
• Public website and competition pages
• Admin dashboard development
• Organizer dashboard development
• Contestant portal development
• RBAC and permissions
• Payment gateway integration
• Vote ledger and revenue settlement logic
• Contestant application workflow
• Competition branding tools
• Leaderboard graphics generation
• Judging and scoring workflows
• Reports, analytics, exports, notifications, and operational tooling

I also handled client feedback cycles across UI, workflows, business rules, and production edge cases to protect financial paths and maintain architectural flexibility.

Tech Stack#

• Frontend: Next.js, React, TypeScript, Tailwind CSS, Radix UI, shadcn-style components, Lucide icons
• Backend: Next.js App Router API routes, feature-based controllers and services
• Database: PostgreSQL with Prisma
• Payments: Stripe and Paystack
• Authentication & Authorization: JWT, HTTP-only refresh flow, bcrypt, CASL abilities, role and permission tables
• Emails: Nodemailer with reusable email templates
• Real-time: Socket.IO, Redis adapter, notification publisher
• Exports & Reports: CSV, XLSX, PDF, jsPDF, workbook abstraction
• Media: Local image/document/video storage helpers, upload validation, image serving route, QR code support
• Graphics: Browser canvas rendering, custom templates, self-hosted fonts, saved graphic thumbnails
• Content Editing: TipTap rich-text editor and JSON content rendering
• Infrastructure Helpers: Docker Compose, health routes, deployment scripts, cron routes, system settings

Architecture#

The codebase follows a feature-based structure:

• API routes act as entry points.
• Controllers handle request parsing and response shape.
• Services handle business rules and database access.
• Shared logic lives in lib modules for auth, errors, Prisma, exports, storage, dates, validation, URLs, indexing, and request metadata.

Core feature modules include:

• Auth and permissions
• Organizers and teams
• Competitions
• Contestants
• Contestant applications
• Application review
• Competition branding
• Leaderboard graphics
• Saved graphics
• Payments
• Coupons
• Bonus votes and sharing
• Membership
• Judging
• Reports and analytics
• Payouts
• Pages and platform settings
• Notifications
• Audit logs
• Health and support

Core Product: Competitions, Contestants, and Voting#

The foundation of Imperial Votes is competition management.

Admins and organizers can create competitions with names, slugs, location, dates, timezones, currency, descriptions, rules, status, sponsors, vote bundles, divisions, contestants, public visibility settings, double-vote windows, branding, application settings, judging settings, and leaderboard rules.

Contestants can have profile images, gallery images, country/state, biography, contestant number, division, visibility status, publication status, and linked application history. Organizers can create contestants manually, bulk import them, export them, manage images, and update visibility.

The public side exposes competition pages, contestant voting pages, leaderboards, competition directories, pricing pages, contact pages, join pages, terms pages, judging criteria pages, and dynamic content pages.

The platform supports core voting flows:

1. Voter selects a contestant
2. Voter selects a vote bundle
3. Voter enters email and accepts terms
4. System creates an order
5. Gateway payment is initialized
6. Webhook or verification confirms payment
7. Vote ledger records the votes
8. Leaderboard reflects the new totals
9. Confirmation page gives the voter a result and optional share flow

The vote ledger acts as the authoritative source of truth. Reports, leaderboards, analytics, and graphics all calculate metrics from ledger-backed entries.

Payments, Vote Ledger, and Money Safety#

Payment and vote allocation were central to the build.

Imperial Votes supports Stripe and Paystack with a gateway-aware checkout service that snapshots revenue share, applies coupons when allowed, records voter metadata, handles terms acceptance, and creates payment transactions.

The vote ledger is built around idempotency to ensure replayed webhooks, duplicate callbacks, refreshes, retries, or delayed gateway responses never double-credit votes.

The system enforces this through:

• Order status checks before settlement
• Atomic transaction updates
• Database uniqueness around ledger entries
• Payment transaction records
• Webhook event tracking
• Gateway reconciliation backstops
• Manual review states for unsafe payment outcomes

Double-vote campaigns are isolated from base paid votes. A voter may receive bonus credits during a promotional window, but base vote counts reflect actual monetary transactions to preserve revenue-share accuracy.

Membership, Revenue Share, and Feature Gating#

The platform supports organizer membership tiers (Growth and Elite) managed directly from the admin interface.

Membership affects several business rules:

• Tier-based revenue-share adjustments
• Access to premium tools: teams, granular roles, deep reporting, exports, double-vote campaigns, and bonus-share campaigns
• Verified badges and prioritized directory placement
• Entry fee handling rules

These rules are enforced at the service and API boundary layer rather than purely via UI state.

Contestant Applications and Entry Fees#

Imperial Votes includes a contestant application workflow:

• Organizer Tools: Start/end dates, custom intake questions, photo/document requirements, video uploads, entry fees, application terms, judging criteria, and public gallery displays.
• Contestant Portal: Account creation, draft saves, media uploads, custom question responses, terms acceptance, entry fee payments, and live status tracking.
• Review & Processing: Application review screens, note keeping, revision requests, waitlisting, rejections, approvals, bulk approvals, bulk email dispatches, application exports, and bulk image downloads.

Approval can automatically materialize a contestant record, assign contestant numbers, preserve uploaded media, notify the applicant, and accrue entry-fee liabilities.

Judging and Scoring Platform#

Imperial Votes provides a formal judging workflow for structured scoring beyond public voting:

• Configuration: Weighted judging rounds, custom criteria with max scores, participant selection, scorecard contestant ordering, public judging links, and secure judge access codes.
• Evaluation: Score submission per criterion, fairness declarations, signature capture, email capture, and single-scorecard enforcement per judge.
• Scoring Engine: Aggregates weighted rounds, criteria scores, manual score inputs (e.g., social challenges), and normalized vote counts into final results with export support.

Scoring criteria are locked upon receiving scorecards to prevent silent data corruption.

Competition Branding System#

Organizers can customize the appearance of their public competition and voting pages through an integrated branding engine:

• Theme and button colors
• Background image, overlay, and blur parameters
• Typography pairs and layout variants
• Sponsor display configurations
• Logo and banner asset management
• Desktop and mobile preview modes
• Color contrast validation to ensure text accessibility before saving

Leaderboard Graphics Generator#

An integrated canvas-based generator creates social media graphics derived directly from real-time leaderboard data:

• Competition picker with Top 3, Top 6, and Top 10 presets
• Layout templates: ranking cards, ranking list, spotlight, and podium top 3
• Aspect ratio customization and dimension presets
• Custom headlines, titles, and period labels
• Self-hosted display fonts for rendering consistency across operating systems
• Color overrides, background uploads, and logo scaling
• Sponsor logo inclusion and placement options
• Thumbnail previews and scoped graphic saving for organizer teams

Image assets are strictly scoped to the owning actor and graphic entity to prevent unauthorized cross-tenant mutations.

Sponsors, Sharing, and Bonus Votes#

• Sponsors: Attached to competitions, rendered across public pages, prioritized by display order, and tracked for impressions and click-through rates.
• Trackable Sharing: Post-payment signed share tokens generate short URLs with click attribution and configurable bonus vote rules.
• Anti-Abuse: Scheduled delay triggers, captcha validation, manual bonus overrides, revocation paths, and audit logging.

Dashboards & Portals#

Admin Dashboard#

• Platform overview, tenant management, and system-wide competition oversight
• Financial tracking: payouts, support transactions, order monitoring, and manual review queues
• Role management, system health metrics, audit logs, and global platform settings

Organizer Dashboard#

• Competition setup, division mapping, and sponsor configuration
• Contestant intake, image pairing, and bulk import/export utilities
• Live order tracking, judging management, and branding customizers
• Team invitations, scoped permissions, and payout requests

Contestant Portal#

• Self-service onboarding, email verification, and password management
• Application drafting, document submissions, and approval status tracking
• Gallery management and notifications

Role-Based Access Control#

The platform implements CASL-based authorization backed by database permission records across super admins, organizer admins, organizer editors, organizer viewers, team members, and public voters. All tenant boundaries and resource actions (competitions, finance, applications, judging, and graphics) are verified within backend API services.

Reports, Analytics, and Exports#

Unified reporting services utilize a workbook abstraction layer to generate CSV, XLSX, and PDF exports without redundant logic:

• Financial breakdowns (revenue share, platform cuts, liabilities, payouts)
• Voting metrics and contestant performance
• Application logs and entry fee volume
• Sponsor engagement analytics (impressions/clicks)
• Operational signals (failed webhooks, delivery retries, manual reviews)

Notifications and Real-Time Infrastructure#

• Event Bus: Dispatches notifications for paid votes, payment failures, submissions, competition status shifts, payout actions, and team updates.
• Multi-Channel Delivery: In-app notifications with read/archive states and transactional email dispatches via Nodemailer.
• Real-Time Engine: Token-authenticated Socket.IO server utilizing a Redis adapter for horizontally scalable event broadcasting.

Content and Operational Quality#

• CMS Pages: Slug-based rich-text content engine with reserved-slug protections for marketing and policy routes.
• Operational Hardening: Health probes (database, memory, ping), config-driven credentials, maintenance cron jobs, audit logs, and strict upload validators.

Key Features Delivered#

• Built from scratch with Next.js, React, TypeScript, Prisma, and PostgreSQL
• Public competition directory and dynamic competition/voting pages
• Public leaderboards with real-time ranking calculations
• Paid vote checkout via Stripe and Paystack
• Idempotent, atomic vote ledger and double-vote promo engines
• Coupon discounts and checkout recovery pipelines
• Role-based access control with multi-tenant isolation
• Contestant intake portal with file uploads, entry fees, and review tools
• Multi-round judging engine with weighted scoring and signature sign-offs
• Per-competition branding engine with accessibility contrast validation
• Canvas-based leaderboard graphics generator with exportable social templates
• Referral tracking, signed share tokens, and attribution bonuses
• Shared reporting engine exporting to CSV, XLSX, and PDF
• Socket.IO real-time notification engine with Redis clustering support
• Built-in CMS engine for marketing and static policy pages

Why This Project Mattered#

Imperial Votes unifies complex sub-systems into a cohesive platform: financial settlement, idempotent vote accounting, multi-stage application review, weighted competition judging, white-label branding, automated social media asset generation, and role-based tenant isolation.

The Result#

A complete SaaS competition platform operating in production: platform operators maintain financial and tenant oversight, organizers run end-to-end events with custom branding, contestants manage applications and profiles, judges evaluate contestants objectively, and voters purchase vote bundles securely.

Portfolio Summary#

Imperial Votes is a custom online voting and competition management platform for pageants, modeling competitions, and public contests. I built the project from scratch with Next.js, React, TypeScript, Prisma, PostgreSQL, Stripe, Paystack, and a feature-based backend architecture.

The platform started with the core idea of competitions, contestants, paid votes, and leaderboards, then grew into a full SaaS product. It includes public competition pages, contestant voting pages, public leaderboards, admin and organizer dashboards, contestant portals, role-based permissions, vote bundles, coupons, payments, webhooks, an atomic vote ledger, double-vote campaigns, revenue share, reports, analytics, membership plans, sponsor tracking, notifications, and payouts.

Two major custom features make the project stand out: a per-competition branding system that lets organizers customize public pages with accessibility contrast validation, and a canvas-based leaderboard graphics generator that creates exportable social media assets from live competition standings.