Skip to content

Latest commit

 

History

History
460 lines (349 loc) · 17.1 KB

README.md

File metadata and controls

460 lines (349 loc) · 17.1 KB

WeWrite

License Node Next.js TypeScript

A social wiki where every page you write is a fundraiser.

WeWrite transforms knowledge sharing into a collaborative economy where writers earn direct USD payments from their contributions and readers support creators with transparent monthly funding.

Table of Contents

🌐 Connect With Us

✨ What Makes WeWrite Special

  • 📝 Collaborative Writing - Create and edit pages together with smart versioning
  • 💰 Direct USD Payments - Support creators with transparent monthly funding
  • 🔗 Smart Linking - Connect ideas across the platform with inline pill links
  • 🌙 Beautiful Interface - Clean, modern design with dark mode and glassmorphism
  • 🔒 Secure & Private - Your data is protected and encrypted
  • ⚡ High Performance - 90% cost reduction through optimization strategies

🚀 Quick Start

Prerequisites

  • Node.js 20.x or higher
  • Bun (preferred package manager - faster than npm/pnpm)

Installation

# Install Bun if you don't have it
curl -fsSL https://bun.sh/install | bash

# Clone the repository
git clone https://github.com/WeWriteApp/WeWrite.git
cd WeWrite

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Run the development server
bun dev

Open http://localhost:3000 to see WeWrite in action!

🏗️ System Architecture

High-Level Architecture

graph TB
    subgraph "Client Layer"
        Web[Next.js Web App]
        PWA[Progressive Web App]
    end

    subgraph "API Layer"
        API[API Routes]
        Webhooks[Stripe Webhooks]
        Cron[Cron Jobs]
    end

    subgraph "Service Layer"
        Auth[Authentication Service]
        Payment[Payment Service]
        Earnings[Earnings Service]
        Email[Email Service]
        Search[Search Service]
    end

    subgraph "Data Layer"
        Firebase[(Firebase)]
        Firestore[(Firestore DB)]
        Storage[(Firebase Storage)]
    end

    subgraph "External Services"
        Stripe[Stripe Payments]
        Resend[Resend Email]
    end

    Web --> API
    PWA --> API
    API --> Service Layer
    Webhooks --> Service Layer
    Cron --> Service Layer
    Service Layer --> Data Layer
    Payment --> Stripe
    Email --> Resend
    Auth --> Firebase
Loading

Payment Flow Architecture

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Stripe
    participant Database
    participant Cron

    User->>Frontend: Subscribe ($10, $20, $30)
    Frontend->>API: Create Subscription
    API->>Stripe: Create Checkout Session
    Stripe-->>User: Payment Page
    User->>Stripe: Complete Payment
    Stripe->>API: Webhook: subscription.created
    API->>Database: Create USD Balance

    User->>Frontend: Allocate to Creators
    Frontend->>API: Set Allocations
    API->>Database: Store Allocations

    Note over Cron,Database: End of Month
    Cron->>Database: Calculate Earnings
    Cron->>Database: Lock Allocations
    Cron->>Stripe: Process Payouts
    Stripe-->>Database: Update Payout Status
Loading

Data Flow

graph LR
    A[User Subscription] --> B[USD Balance]
    B --> C[Monthly Allocations]
    C --> D[Creator Earnings]
    D --> E[Payouts]

    F[Unallocated Funds] --> G[Platform Revenue]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style E fill:#fff9c4
    style F fill:#ffebee
    style G fill:#fce4ec
Loading

Environment Architecture

graph TD
    subgraph "Development"
        DevBranch[dev branch]
        DevCollections[DEV_* Collections]
        DevData[Test Data]
    end

    subgraph "Production"
        MainBranch[main branch]
        ProdCollections[Production Collections]
        RealData[Real User Data]
    end

    DevBranch --> DevCollections
    DevCollections --> DevData
    MainBranch --> ProdCollections
    ProdCollections --> RealData

    style DevBranch fill:#e3f2fd
    style MainBranch fill:#e8f5e9
Loading

🛠️ Technology Stack

Core Technologies

  • ⚛️ Next.js 14 - React framework with App Router
  • 🔥 Firebase - Backend-as-a-Service platform
  • 🎨 Tailwind CSS - Utility-first CSS framework
  • 📝 Slate.js - Customizable rich text editor framework
  • 💳 Stripe - Payment processing and subscriptions
  • 🔍 TypeScript - Type-safe JavaScript development

Firebase Services

  • 🗄️ Firestore - NoSQL document database for pages, users, and versions
  • 🔐 Authentication - Email/password authentication with session management
  • ☁️ Functions - Serverless functions for webhooks and background processing
  • 📁 Storage - File storage for images and attachments

Development & Deployment

  • 📦 Bun - Fast, disk space efficient package manager
  • 🚀 Vercel - Deployment platform with automatic CI/CD
  • 📊 LogRocket - Session replay and error tracking

Key Features

  • 🌙 Dark Mode - System-aware theme switching with OKLCH color system
  • 📱 Responsive Design - Mobile-first responsive interface
  • 🔗 Smart Linking - Automatic page linking and backlinks with inline pills
  • 💰 USD Creator Support - Direct USD payments with transparent monthly funding
  • 🔒 Security - Comprehensive security measures and data protection
  • ⚡ Performance - 90% cost reduction through aggressive optimization

📚 Documentation

Essential Documentation (Start Here)

Core Systems

Authentication & Security

Payment & Financial System

Content & Editor

Search & Discovery

SEO & Content Discovery

  • UGC SEO Architecture - Complete SEO implementation for user-generated content
    • Server-side rendering for search engines and AI crawlers
    • Schema.org structured data (Article, Person, BreadcrumbList)
    • Dynamic sitemaps for pages, users, and news content
    • AI search optimization through semantic HTML and rich metadata

UI & Design

Performance & Optimization

Deployment & Operations

Development Standards

Full Documentation Index

For a complete list of all documentation, see docs/README.md.

📁 Project Structure

WeWrite/
├── app/                      # Next.js App Router
│   ├── api/                 # API routes and endpoints
│   │   ├── admin/          # Admin API endpoints
│   │   ├── cron/           # Scheduled job endpoints
│   │   └── webhooks/       # Stripe webhook handlers
│   ├── admin/              # Admin dashboard pages
│   ├── auth/               # Authentication pages
│   ├── components/         # Reusable UI components
│   │   ├── admin/         # Admin-specific components
│   │   ├── editor/        # Rich text editor components
│   │   ├── landing/       # Landing page components
│   │   ├── layout/        # Layout components
│   │   ├── payments/      # Payment UI components
│   │   └── ui/            # Shared UI components
│   ├── contexts/           # React contexts for global state
│   ├── hooks/              # Custom React hooks
│   ├── lib/                # Utility libraries and helpers
│   ├── providers/          # Context providers
│   ├── services/           # Business logic services
│   ├── settings/           # User settings pages
│   └── utils/              # Utility functions
├── docs/                   # Technical documentation
│   ├── architecture/       # System architecture docs
│   ├── auth/              # Authentication docs
│   ├── deployment/        # Deployment guides
│   ├── editor/            # Editor documentation
│   ├── features/          # Feature-specific docs
│   ├── firebase/          # Firebase patterns
│   ├── payments/          # Payment system docs
│   ├── performance/       # Performance guides
│   ├── search/            # Search system docs
│   ├── security/          # Security documentation
│   ├── seo/               # SEO and content discovery docs
│   └── ui/                # UI and design docs
├── functions/              # Firebase Cloud Functions
├── public/                 # Static assets
│   ├── icons/             # App icons and favicons
│   └── images/            # Images and graphics
└── scripts/                # Build and utility scripts

Key Directories

  • app/ - Next.js 14 App Router with file-based routing
  • app/components/ - Reusable UI components organized by feature
  • app/services/ - Business logic services (payment, earnings, email, etc.)
  • app/api/ - API routes for backend functionality
  • docs/ - Comprehensive technical documentation
  • functions/ - Firebase Cloud Functions for webhooks and background tasks

🔧 Development

Development Commands

# Start development server
bun dev

# Start with HTTPS (for PWA testing)
bun dev:https

# Build for production
bun build

# Run tests
bun test

# Run tests in watch mode
bun test:watch

# Run specific test suites
bun test:payments
bun test:payouts
bun test:allocation

Branch-Aware Environment

WeWrite uses branch-aware environment detection for local development:

  • Main branch (main): Uses production collections - connects to real data
  • Dev branch (dev): Uses dev collections (DEV_* prefix) - isolated test data
  • Other branches: Uses dev collections (safe default) - isolated test data

This ensures you can test against production data when needed (main branch) while keeping development work safely isolated (dev branch).

Code Quality

Before contributing, ensure you follow:

  1. TypeScript strict mode - All code must be type-safe
  2. ESLint rules - Run bun lint before committing
  3. Security guidelines - Follow USERNAME_SECURITY_GUIDELINES
  4. Performance practices - Follow PERFORMANCE_OPTIMIZATION_GUIDE

🚀 Deployment

Automatic Deployment

WeWrite uses Vercel for automatic deployment:

  • Production: Deploys from main branch to wewrite.app
  • Preview: Deploys from dev branch for testing
  • Environment Variables: Configured in Vercel dashboard

See Production Deployment Guide for detailed procedures.

🤝 Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Follow our coding standards (see documentation)
  4. Write tests for new functionality
  5. Commit your changes with clear messages
  6. Submit a pull request

Development Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help create a welcoming environment for all contributors

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.

This is free software: you are free to change and redistribute it under the terms of the GPL-3.0 license.

💬 Support

🙏 Acknowledgments

Built with modern web technologies and powered by:

Made with ❤️ by the WeWrite team

⬆ Back to top