286 lines
11 KiB
Markdown
286 lines
11 KiB
Markdown
# 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.* |