waylume_server/MANIFESTO.md

The Waylume Manifesto

Project Overview

Waylume is a VPN service consisting of three main components: a Flutter client application, Supabase backend with edge functions, and self-managing WireGuard server nodes. This manifesto documents the current architecture and implementation patterns based on the existing codebase.

System Architecture

Current Component Structure

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│                 │    │                 │    │                 │
│  Flutter Client │◄──►│ Supabase Cloud  │◄──►│ Waylume Servers │
│      App        │    │   (Backend)     │    │    (Nodes)      │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                        │                        │
        │                        │                        │
        ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Device   │    │  PostgreSQL +   │    │   WireGuard     │
│   (iOS/Android/ │    │  Edge Functions │    │   Interface     │
│    Desktop)     │    │   + Stripe      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Component Breakdown

Frontend: Flutter Client Application

Repository: Waylume VPN
Technology Stack: Flutter 3.9+, Provider state management, Go Router, ShadCN UI
Purpose: Cross-platform VPN client with subscription management

Current Features:

• WireGuard VPN integration
• Interactive map-based server selection (Mapbox)
• Authentication system (email/password)
• Stripe-powered subscription management with trial support
• Payment history and account management
• Real-time connection status monitoring
• Bottom sheet interface with connection controls

File Structure:

lib/
├── pages/           # Application screens (home, login, register, account, payment, plans, stripe_portal)
├── providers/       # State management (vpn_connection, subscription)
├── widgets/         # UI components (server_map, connection_status, home_bottom_sheet, stripe components)
├── backend/         # API utilities
├── themes/          # UI theming
└── utils/           # Helper functions

Backend: Supabase Edge Functions

Repository: Waylume Supabase Edge Functions
Technology: Deno with TypeScript, PostgreSQL, Stripe integration
Purpose: Business logic layer between client and server nodes

Implemented Edge Functions:

1. vpn-nodes-list (GET, no auth)

   • Returns available VPN servers from waylume_servers table
   • Filters for servers with valid coordinates
   • Provides geolocation data (country, city, coordinates)

2. connection-request (POST, Bearer token or user_id)

   • Creates VPN sessions in database
   • Calls Waylume Server API to generate WireGuard peer
   • Returns peer configuration to client

3. serve-payment (POST, no auth required)

   • Creates Stripe checkout sessions
   • Handles both one-time and subscription billing
   • Manages trial period eligibility

4. stripe-webhook (POST, signature verification)

   • Processes Stripe webhook events
   • Handles: checkout completion, subscription renewals, cancellations, updates
   • Maintains Stripe-database synchronization

5. query-transactions (GET, Bearer token)

   • Multi-endpoint: /payments, /subscriptions, /overview
   • Provides transaction history with filtering and pagination
   • Supports date filtering, sorting, and totals

6. cancel-subscription (POST, Bearer token)

   • Validates user ownership
   • Schedules cancellation through Stripe API

7. serve-portal (POST, Bearer token)

   • Creates Stripe customer portal sessions
   • Allows subscription and payment method management

Database Schemas:

• Public: waylume_servers, vpn_sessions
• Commerce: products, payments, subscriptions

Infrastructure: Waylume Server Nodes

Repository: Waylume Server
Technology: Dart server application with Docker deployment
Purpose: Self-managing WireGuard VPN nodes

Current Implementation:

• WireGuard Management: Interface initialization (wg0), peer creation/deletion
• Traffic Control: HTB-based speed limiting, iptables quota enforcement
• Peer Isolation: iptables rules preventing peer-to-peer communication
• Server Registration: Automatic registration with Supabase backend
• Health Monitoring: Continuous heartbeat system
• IP Management: Automatic assignment from 10.0.0.0/24 range

API Endpoints (Internal use only - called by Supabase Edge Functions):

• POST /api/peers - Create peer with generated keys and IP
• POST /api/peers/delete - Remove peer and cleanup
• POST /api/peers/speed-limit - Set bandwidth limits (bytes/second)
• POST /api/peers/data-cap - Set data usage quotas (bytes)
• POST /api/peers/config - Retrieve peer config (returns 404 - not implemented)

Network Configuration:

• WireGuard Interface: wg0 on 10.0.0.1/24
• Peer IP Range: 10.0.0.2 - 10.255.255.254
• WireGuard Port: 51820/udp
• API Port: 3000/tcp

Data Flow Patterns

Server Discovery Flow

Flutter App ──► vpn-nodes-list edge function ──► waylume_servers table ──► Server list with geolocation

VPN Connection Flow

User selects server ──► connection-request edge function ──► Server API POST /api/peers ──► WireGuard peer config ──► Client connects
                                    │
                                    ▼
                            vpn_sessions table updated

Payment Flow

Plan selection ──► serve-payment ──► Stripe checkout ──► stripe-webhook ──► Database update ──► Subscription active

Server Health Flow

Waylume Server ──► Heartbeat service ──► waylume_servers.last_heartbeat ──► Server availability status

Technology Stack Rationale

Flutter Frontend

• Cross-platform: Single codebase for iOS, Android, Desktop
• WireGuard Plugin: Native WireGuard integration available
• UI Framework: ShadCN UI for consistent design
• State Management: Provider pattern for connection and subscription state
• Maps: Flutter Map with Mapbox for server selection

Supabase Backend

• PostgreSQL: Full SQL database with Row Level Security
• Edge Functions: Deno runtime for serverless business logic
• Authentication: Built-in JWT-based auth system
• Real-time: WebSocket subscriptions (not currently used but available)
• Global: Edge network for reduced latency

Dart Server Infrastructure

• Language Consistency: Same language as Flutter client
• Process Control: Direct execution of WireGuard and iptables commands
• Docker Deployment: Containerized with network capabilities
• Self-Management: Autonomous registration and health reporting

WireGuard Protocol

• Performance: Minimal overhead and high throughput
• Security: Modern cryptographic protocols
• Mobile-Friendly: Battery efficient and handles network changes
• Simple Configuration: Easy peer management

Current Security Model

API Security

• Internal APIs: Waylume Server APIs are internal-only (no authentication by design)
• Edge Functions: Protected by Supabase JWT tokens where required
• Stripe Integration: Webhook signature verification
• Database: Row Level Security policies

VPN Security

• Peer Isolation: iptables rules prevent peer-to-peer communication
• Traffic Control: Per-peer bandwidth and data limits
• Key Management: Client-side key generation, server manages peer configs
• Network Segmentation: Dedicated IP ranges for VPN traffic

Payment Security

• Stripe Integration: PCI-compliant payment processing
• Webhook Verification: Cryptographic signature validation
• User Validation: Subscription ownership verification for cancellations

Development Standards

Code Organization

waylume-client/          # Flutter application
├── lib/pages/          # Application screens
├── lib/providers/      # State management
├── lib/widgets/        # Reusable UI components
├── lib/backend/        # API utilities
└── lib/themes/         # UI theming

waylume-server/          # VPN node server
├── lib/config/         # Supabase configuration
├── lib/services/       # Core services
├── lib/web/            # HTTP routes
├── lib/wireguard/      # WireGuard functionality
└── lib/main.dart       # Entry point

waylume-supabase/        # Edge functions
├── functions/vpn-nodes-list/
├── functions/connection-request/
├── functions/serve-payment/
├── functions/stripe-webhook/
├── functions/query-transactions/
├── functions/cancel-subscription/
└── functions/serve-portal/

Naming Conventions

• Files: snake_case (Dart standard)
• Database Tables: snake_case with descriptive prefixes
• Environment Variables: SCREAMING_SNAKE_CASE
• API Endpoints: kebab-case paths

Environment Configuration

Waylume Server:

SUPABASE_URL=project_url
SUPABASE_KEY=anon_key
SERVER_ID=unique_identifier
EXTERNAL_PORT=3000

Supabase Functions:

SUPABASE_URL=project_url
SUPABASE_SERVICE_ROLE_KEY=service_key
STRIPE_SECRET_KEY=stripe_key
STRIPE_WEBHOOK_SECRET=webhook_secret

Current Limitations

Known Gaps (from TODO.md)

Security:

• No API authentication on Waylume Server (by design - internal use)
• No rate limiting implemented
• No HTTPS/TLS support documented

Monitoring:

• Basic logging only
• No comprehensive health check endpoints
• No metrics collection system

API Coverage:

• GET /api/peers (list peers) - not implemented
• GET /api/peers/{id} (specific peer info) - not implemented
• POST /api/peers/config - returns 404

Testing:

• Manual testing only
• No automated test suite
• No unit or integration tests

Deployment Patterns

Docker-Based Deployment

• Waylume Server: Docker Compose with network capabilities
• Required Capabilities: NET_ADMIN for WireGuard interface management
• Port Mapping: 3000 (API), 51820 (WireGuard)
• Volume Mounting: WireGuard runtime directory

Environment Detection

• Automatic environment detection in Waylume Server
• Environment variable configuration across all components
• Docker environment configuration support

---

This manifesto documents the current state of the Waylume project based on existing implementation. It should be updated as new features are added or architectural changes are made.