Revenue Integrity Platform — Hackathon Submission
A production-grade, full-stack platform that fairly distributes revenue among content creators using a 13-algorithm fairness engine, statistical manipulation detection, and a cryptographically verifiable audit chain.
Platforms that distribute revenue among creators based on engagement metrics are vulnerable to artificial inflation. View bots, like farms, and coordinated comment manipulation allow bad actors to claim disproportionate payouts at the expense of genuine creators. No existing platform provides creators with a transparent, mathematical explanation of exactly how their payout was calculated — or why it may have been reduced.
RevFair OS solves both problems simultaneously: it detects and penalizes manipulation while giving every creator a human-readable, cryptographically-sealed explanation of their exact payout computation.
The creator-facing dashboard displays live earnings, FairScore, trust status, and a Crex-style analytics chart with metric switching (Views, Likes, Comments, Watch Time) and a per-bar performance indicator relative to the creator's own average.
Detailed breakdown of the creator's projected distribution for the current cycle. Shows the formula attribution (Normalized Engagement, Trust Multiplier, Risk Penalty) with a dark payout card, cycle metadata, and exportable statement download.
Per-video engagement table showing Views, Likes, Comments, and Watch Time for every imported content item. Supports full-text search and verification status per item.
The content import tool. Paste any YouTube video URL and the system fetches real engagement data via the YouTube Data API, or falls back to a high-fidelity simulation if no API key is configured. All imported data is committed to the audit chain.
After a successful sync, the system shows the ingested video thumbnail, verified metrics (views, likes, comments, watch time), and a Revenue Impact Analysis panel showing the predicted FairScore delta, predicted payout change, and integrity signal explanations.
The transparency page shows the exact mathematical formula used to compute the creator's FairScore with live numbers: FairScore = NormalizedEngagement x Trust x (1 - Risk). This is not a display — it is computed server-side and shown as a human-readable proof.
The lower section of the transparency page shows every decision bullet generated by the engine for this creator's cycle. Positive signals (green) and risk signals (red/blue) are listed with the exact Algo tag that triggered them. The "Optimize My Content" CTA links to the data-driven content optimizer.
The admin-facing command center provides a global overview of the current distribution cycle: revenue pool size, fraud exposure prevented (dollar amount), high-risk flags count, and platform health score. The Payout Distribution Analysis chart and the Integrity Stream live feed are shown below.
When an admin selects a flagged creator in the Fraud Review Console, a detail drawer opens showing the exact risk score, the specific manipulation signals that fired (with algorithm tags), and the raw engagement metrics that triggered them. Admin actions (Approve, Reduce, Investigate) are available from this view.
revfair-os/
backend/
engine/
normalizationEngine.js -- Algos 1, 2 (Min-Max, Weighted Score)
manipulationDetector.js -- Algos 3-8 (EQR, Watch-Time, Spike, Imbalance, Trust, Risk)
distributionEngine.js -- Algos 9-12 (FairScore, Distribution, Raw vs Fair Rank)
services/
fraudService.js -- Algo 7 (Trust EMA), Algo 13 (Exposure Prevented)
auditService.js -- Algo 12 (SHA-256 Hash Chain)
policyService.js -- Policy engine (DB-driven thresholds)
routes/
auth.js -- JWT authentication
internal.js -- Admin governance endpoints
creators.js -- Creator management
engagement.js -- Engagement data ingestion
revenue.js -- Revenue configuration
youtube.js -- YouTube API integration
creatorMe.js -- Creator-specific data endpoints
databaseViewer.js -- Live database exploration
db.js -- Hybrid SQLite / PostgreSQL adapter
initDb.js -- Schema initialization with seeded demo data
server.js -- Express server entry point
frontend/
src/
portals/
internal/ -- Admin portal pages
creator/ -- Creator portal pages
components/layout/ -- Shared layout components
utils/
certificateGenerator.js -- Canvas-based audit certificate download
context/AuthContext.jsx -- JWT auth context
All 13 algorithms are documented inline in the source code with the exact formula and implementation rationale.
| Algorithm | Formula | File | Purpose |
|---|---|---|---|
| 1. Min-Max Normalization | value / max(all values) | normalizationEngine.js | Scales all metrics to 0-1 relative to peers |
| 2. Weighted Engagement Score | (V x wV) + (L x wL) + (C x wC) + (W x wW) | normalizationEngine.js | Configurable metric weighting |
| 3. Engagement Quality Ratio | (likes + comments) / max(views, 1) | manipulationDetector.js | Filters passive view inflation |
| 4. Watch-Time Quality | watchTime / views | manipulationDetector.js | Detects click-and-leave bot traffic |
| 5. Spike Detection | views > mean + 3 x std (statistical) | manipulationDetector.js | Flags statistically anomalous surges |
| 6. Comment Imbalance | comments / views < threshold | manipulationDetector.js | Detects coordinated view pumping |
| 7. Trust Score EMA | T_new = T_old x 0.85 + outcome x 0.15 | fraudService.js | Gradual trust evolution |
| 8. Risk Score Aggregation | Sum(flag_i x weight_i), capped at 1.0 | manipulationDetector.js | Composite fraud score |
| 9. Fair Score Formula | NormEngagement x Trust x (1 - Risk) | distributionEngine.js | Core payout merit calculation |
| 10. Revenue Distribution | (FairScore / Sum FairScores) x Pool | distributionEngine.js | Zero-sum proportional payout |
| 11. Fraud Review Workflow | Flag / Approve / Reduce / Investigate | fraudService.js | Human-in-the-loop governance |
| 12. Audit Hash Chain | SHA256(H_prev + ts + action + entity + meta) | auditService.js | Tamper-evident immutable log |
| 13. Fraud Exposure Prevented | Sum(rawPotential - actualPayout) for risky creators | fraudService.js | Dollar-value of blocked manipulation |
Revenue Management
- Admin-configurable revenue pool with weight sliders for Views, Likes, Comments, and Watch Time
- Server-side validation ensuring weights always sum to 1.0
- Every configuration change is written to the audit chain
Engagement Normalization
- Min-Max normalization across all creators in the current cycle
- Normalized component scores (nViews, nLikes, nComments, nWatchTime) computed per creator
Manipulation Detection
- Statistical spike detection using mean + 3 standard deviations
- Watch-time integrity check (minutes per view threshold)
- Engagement quality ratio check (likes + comments vs views)
- Comment imbalance detection (comment rate vs views)
- Suspicious like ratio detection (too high or too low)
- Policy-driven thresholds configurable from the admin console
Fair Distribution
- Raw Rank vs Fair Rank comparison showing exactly how fraud penalties shift creator rankings
- Zero-sum guarantee: payout sum always equals the configured pool amount
- Creators cannot game a single metric — all three dimensions (engagement, trust, risk) must be clean
Algorithmic Transparency
- Creator-facing transparency page showing the exact formula and live values used for their calculation
- Decision logic bullets explaining each positive and negative signal in plain English
- Audit certificate download (Canvas-generated, branded, includes formula proof and SHA-256 hash)
Audit Chain
- Every system event (config change, data import, fraud action, cycle lock) generates an immutable log entry
- SHA-256 hash chaining links each entry to the previous one
- verifyChain() function re-computes the full chain on every audit log page load and shows a green/red integrity banner
Database Explorer
- Live SQL table viewer available at /internal/database
- Judges can browse anomaly_flags, audit_logs, engagement_metrics, and creators tables directly in the browser without any external tool
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Recharts, Framer Motion, Tailwind CSS |
| Backend | Node.js, Express.js |
| Database | SQLite (local demo), PostgreSQL (production) |
| Authentication | JWT with role-based access control (admin, analyst, creator) |
| Charting | Recharts (Area, Bar, Composed, Radar, Line charts) |
| PDF Generation | HTML5 Canvas API (no external library) |
| External API | YouTube Data API v3 with graceful mock fallback |
- Node.js 18 or later
- A YouTube Data API v3 key (optional — system falls back to demo data if absent)
cd backend
npm install
cd ../frontend
npm install
Create backend/.env:
PORT=3001
JWT_SECRET=REVFAIR_SECRET_HACKATHON_2024
YOUTUBE_API_KEY=your_key_here
cd backend
node initDb.js
node server.js
In a separate terminal:
cd frontend
npm run dev
Or run start.bat from the project root to start both simultaneously.
| Role | Password | |
|---|---|---|
| Admin | admin@revfair.com | admin123 |
| Creator | creator@revfair.com | creator123 |
- Login as admin at
http://localhost:3000/internal/login - Navigate to Revenue Config and adjust metric weights (Views, Likes, Comments, Watch Time must sum to 100%)
- Navigate to YouTube Import and paste any YouTube URL to ingest engagement data
- Navigate to the Command Center (Dashboard) to see the distribution chart and Raw vs Fair Rank table
- Navigate to Fraud Review Console to see flagged creators and review the exact manipulation reasons
- Navigate to Audit Logs to verify the SHA-256 hash chain integrity
- Lock the cycle via the Lock Cycle button in the Command Center
- Logout and login as creator at
http://localhost:3000/creator/login - Navigate to Transparency to see the mathematical payout proof and download a signed audit certificate
- Navigate to the Algorithm Viewer at
/internal/algorithmsto browse all 13 algorithms with exact source code
To view the live database during a demonstration, navigate to http://localhost:3001/api/internal/database (requires admin JWT), or use the in-app Database Explorer at /internal/database.
Alternatively, inspect the SQLite database directly:
cd backend
node inspect-db.js
This prints all tables and recent records to the console.
MIT License. Built for the Revenue Distribution Engine with Manipulation Resistance hackathon challenge.