A modern, API-first micropayment platform for quality journalism. Built with Flask (backend) and vanilla JavaScript SPA (frontend).

• Python 3.9+
• pip and virtualenv

1. Clone and setup virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure environment (optional):

cp .env.example .env
# Edit .env with your settings (defaults work for demo)

3. Initialize database and seed demo data:

python seed.py

4. Run the development server:

python app.py

5. Open in browser:

http://127.0.0.1:51879

• 🏪 Newsstand - Browse publishers with filters, search, and infinite scroll
• 📰 Pay-to-Unlock - One-click micropayments to unlock premium articles
• 💰 Digital Wallet - Preload balance, instant payments, refund window (10 min)
• 🎯 Smart Routing - Client-side SPA with hash-based navigation
• 🔐 Authentication - Email login + magic link support
• 📊 Transaction History - Full audit trail with revenue splits

• 📈 Analytics Console - All-time and 7-day revenue stats with interactive charts
• 💵 Revenue Splits - Configurable split rules by role (author, editor, etc.)
• 📥 CSV Export - Download transaction data
• 👥 Author Management - View and manage author relationships
• 📝 Content Curation - Browse and add independent author submissions
• ⚙️ Publisher Settings - Customize branding, pricing, and author split defaults

• 🎨 Theme Customization - Live theme editor with colors, fonts, gradients
• ⚙️ Site Settings - Toggle navigation items, configure layout

• 🔒 Security - CSRF protection, rate limiting, CORS, security headers
• ⚡ Performance - Lazy loading, skeleton loaders, optimized assets
• ♿ Accessibility - Keyboard navigation, ARIA labels, focus states
• 📱 Responsive - Mobile-first design, touch-friendly interactions
• 🎯 API-First - Comprehensive REST APIs for all operations
• 🎓 Interactive Tours - Guided onboarding for readers, authors, and publishers (Shepherd.js)
• 🎨 Showcase Sites - Branded microsites with custom themes for creators

• Framework: Flask 3.0+ with Blueprints
• Database: SQLAlchemy with SQLite (easily swappable)
• Auth: Flask-Login + JWT tokens
• Validation: Marshmallow schemas
• Security: CSRF, rate limiting, CORS

• Router: Custom hash-based client-side routing
• API Client: Fetch-based API wrapper
• State Management: Simple reactive auth state
• Styling: Modern CSS with design tokens, glassmorphism
• No framework dependencies - Pure vanilla JavaScript

/api
  /auth          - Authentication (login, magic link, logout, me)
  /account       - Wallet and transactions
  /publishers    - Publisher data
  /articles      - Article listings and details
  /categories    - Publisher categories
  /pay           - Payment processing
  /verify        - Payment verification
  /refund        - Refund processing
  /publisher     - Publisher console APIs
  /admin         - Admin APIs (theme, site, splits)

Paypr includes interactive onboarding tours to help you explore the platform:

• Reader Tour - Learn how to browse, unlock articles, and manage your wallet
• Author Tour - Discover how to publish content and track your earnings
• Publisher Tour - Explore content curation and author management

Access tours from the "🎓 Tours" dropdown in the navbar. Tours auto-start for first-time visitors and track completion in localStorage.

1. Browse Publishers - Visit the newsstand at /
2. Login - Click "Login" and enter any email (e.g., [email protected])
   • New accounts automatically get $5.00 starter balance
3. Select Publisher - Click on any publisher to view their articles
4. Read Article - Click an article to see the preview
5. Unlock Content - Click "Unlock Article" to pay and access full content
6. Refund Window - You have 10 minutes to request a refund
7. View History - Check transaction history and wallet balance

Explore two complete showcase sites demonstrating different revenue models:

• URL: http://127.0.0.1:51879/#/showcase/smerconish
• Model: Content from multiple publishers with custom splits
• Examples:
  • CNN articles (45% author / 45% publisher / 10% platform)
  • SiriusXM podcasts (50% / 40% / 10% split)
  • Independent content (90% / 10% split)
• Demonstrates how a creator can aggregate content from various distribution partners

• URL: http://127.0.0.1:51879/#/showcase/technewsletter
• Model: 100% independent creator, no publisher intermediary
• Split: 90% to author, 10% to platform
• Demonstrates the indie creator model with full creative control
• Modern tech-focused design showcasing the platform's flexibility

1. Navigate to the admin login (if needed, create route or use API directly)
2. Default credentials: admin / demo123
3. Customize theme colors, fonts, and site settings

See .env.example for all available options:

Configure revenue splits in the admin panel or via API:

• Platform fee: Set via PLATFORM_FEE_BPS (basis points)
• Publisher splits: Configure per-publisher in admin

While the server is running:

python seed.py

Or use the dev endpoint (requires login):

POST /dev/reseed

Use the included Healthcheck endpoint:

curl http://127.0.0.1:51879/healthz

Example API calls:

# Get publishers
curl http://127.0.0.1:51879/api/publishers

# Get categories
curl http://127.0.0.1:51879/api/categories

# Get article
curl http://127.0.0.1:51879/api/articles/1

PayprProto/
├── app.py                 # Flask app factory
├── config.py             # Configuration classes
├── models.py             # SQLAlchemy models
├── extensions.py         # Flask extensions
├── seed.py              # Database seeder
├── requirements.txt     # Python dependencies
├── blueprints/          # Flask blueprints
│   ├── api.py          # REST API endpoints
│   ├── account.py      # User account routes
│   ├── publisher.py    # Publisher routes
│   ├── admin.py        # Admin routes
│   └── dev.py          # Dev tools
├── services/           # Business logic
│   ├── payments.py    # Payment calculations
│   ├── tokens.py      # JWT handling
│   ├── events.py      # Analytics tracking
│   └── schemas.py     # Validation schemas
├── static/            # Frontend SPA
│   ├── index.html    # SPA entry point
│   ├── app.js        # Main application
│   ├── css/          # Stylesheets
│   └── js/           # JavaScript modules
│       ├── api.js         # API client
│       ├── auth.js        # Auth manager
│       ├── router.js      # Client router
│       ├── components/    # UI components
│       └── pages/         # Page views
└── docs/             # Documentation

pytest

docker compose up --build

Then visit: http://127.0.0.1:51879

Full API documentation available at docs/API.md

Quick reference:

• All API endpoints are under /api/
• Authentication uses session cookies
• Payment APIs require authentication
• Admin APIs require admin session

• CSRF protection on all forms and state-changing operations
• Rate limiting on sensitive endpoints
• Security headers (CSP, X-Frame-Options, etc.)
• JWT tokens for payment verification
• Session-based authentication
• SQL injection protection via SQLAlchemy
• XSS protection via proper escaping

Note: This is a prototype. For production:

1. Use PostgreSQL instead of SQLite
2. Set strong SECRET_KEY and JWT_SECRET_KEY
3. Enable HTTPS and set SESSION_COOKIE_SECURE=True
4. Use Redis for rate limiting and caching
5. Configure proper Stripe webhook handling
6. Set up proper email delivery for magic links
7. Configure Sentry or other monitoring
8. Use a production WSGI server (gunicorn, uwsgi)
9. Set up CDN for static assets

MIT License - See LICENSE file for details

This is a prototype/demo project. Feel free to fork and adapt for your needs!

For questions or issues, please open an issue on GitHub.

Built with ❤️ for quality journalism and micropayments