> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winstory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> High-level technical architecture of Winstory.io and B2C/Agency flows.

## 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)