Skip to main content

​
High-Level Architecture

Winstory.io is a Next.js 15 application with:
  • App Router for the main web app (/app)
  • Mintlify docs for docs.winstory.io
  • Supabase for database, auth, and storage
  • Thirdweb for blockchain integration (Base Sepolia / Base mainnet)

​
Core Components

  • Frontend: Next.js (React, TypeScript)
  • Backend: Next.js API routes (edge & node runtimes)
  • Database: Supabase Postgres
  • Blockchain: Smart contracts (WinstoryCampaigns.sol, reward vaults)
  • Monitoring: Supabase system_error_logs, email alerts, cron jobs

​
B2C/Agency Campaign Flow

  1. Campaign creation
    • Route: POST /api/campaigns/create
    • Validates input, pricing config, and rewards
    • Verifies payment (Stripe or crypto) before persisting campaign
  2. Moderation (hybrid)
    • Tables: moderation_progress, moderation_votes
    • Logic: lib/moderation-engine.ts
  3. Validation & activation
    • Campaign status transitions to APPROVED
    • Short link becomes available (for B2C/Agency & Individual)
  4. Completions & rewards
    • Completions: /api/completions/submit
    • Rewards: reward_distributions, reward vaults on-chain

​
Data Flow: MyWin/Creations

  • Listing: /api/campaigns/moderation?walletAddress=...
    • Includes moderation progress, sessions, blockchain mapping, and agency info
    • Supports server-side pagination via page / pageSize
  • Dashboard: /api/campaigns/dashboard?campaignId=...
    • Returns aggregated metrics for a single campaign
  • Metrics batch: /api/campaigns/metrics/batch
    • Returns metrics for up to N campaigns in one call

​
Error Handling & Monitoring

  • Error logger: lib/error-logger.ts
    • Functions: logError, logApiError, resolveError
    • Stores errors in system_error_logs
  • Alerts: lib/alert-service.ts
    • Sends email alerts for critical errors
  • Cron jobs:
    • /api/cron/monitor-resources — infra & quotas
    • /api/cron/check-error-alerts — error summaries
    • /api/cron/monitor-onchain — on-chain consistency

​
Rate Limiting & Protection

  • Middleware: middleware.ts
    • Simple per-IP + path rate limiting for /api/* and /c/*
    • Intended as a baseline; should be complemented by WAF / external rate limiter in production

​
Future Improvements

  • Full OpenAPI/Swagger spec generated from source
  • Central distributed tracing (OpenTelemetry) exported to Grafana/Datadog
  • Dedicated metrics pipeline for business KPIs (completion funnel, ROI per segment)