# 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**:
```env
SUPABASE_URL=project_url
SUPABASE_KEY=anon_key
SERVER_ID=unique_identifier
EXTERNAL_PORT=3000
```

**Supabase Functions**:
```env
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.*