Add Waylume Manifesto and update API routes for peer management
This commit is contained in:
ImBenji
286
MANIFESTO.md
Normal file
286
MANIFESTO.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user