Product Requirements Document (PRD) - HiddenRoute VPN
Version: 2.0
Date: 2024-12-28
Status: Active Development
Classification: Confidential
Table of Contents
- Executive Summary
- Product Vision & Strategy
- Market Analysis & Positioning
- User Personas & Journey Maps
- System Architecture
- Functional Requirements
- Technical Requirements
- Security & Compliance Framework
- User Interface Design
- Development Roadmap
- Testing & Quality Assurance
- Deployment & Operations
- Business Model & Monetization
- Risk Assessment & Mitigation
- Project Directory Structure
- Technical Documentation Requirements
- Success Metrics & KPIs
- Implementation Status
- Appendices
1. Executive Summary
1.1 Product Overview
HiddenRoute VPN is a revolutionary privacy solution that combines local virtualization technology with advanced network security features to provide users with complete anonymity and protection without relying on third-party VPN servers. By utilizing a locally-run OpenWrt virtual machine managed through VirtualBox, HiddenRoute offers:
- Zero-Trust Architecture: All traffic processing happens locally on user's device
- Triple-Layer Protection: DPI bypass, ad-blocking, and optional Tor routing
- One-Click Simplicity: Complex technology made accessible to non-technical users
- No External Dependencies: Complete privacy without trusting external VPN providers
1.2 Key Differentiators
- Local Processing: Unlike traditional VPNs, no user data leaves the device to third-party servers
- VM-Based Isolation: Enhanced security through virtualization
- Transparent Operations: Open-source OpenWrt base ensures auditability
- Integrated Ad-Blocking: Built-in privacy protection beyond just VPN
- Optional Tor Integration: Additional anonymity layer when needed
1.3 Target Market
- Primary: Privacy-conscious individuals in censorship-heavy regions
- Secondary: Security researchers, journalists, and activists
- Tertiary: General consumers seeking ad-free browsing
1.4 Business Goals
- Year 1: 10,000 active users, 20% conversion rate
- Year 2: 50,000 active users, expand to Linux/macOS
- Year 3: 200,000 active users, enterprise offerings
2. Product Vision & Strategy
2.1 Vision Statement
"To democratize digital privacy by providing enterprise-grade security tools in a consumer-friendly package, ensuring every individual can protect their online identity without technical expertise or trust in third parties."
2.2 Mission Statement
"HiddenRoute empowers users to reclaim their digital privacy through innovative local virtualization technology, combining the power of DPI bypass, ad-blocking, and Tor anonymization in a single, user-friendly application."
2.3 Strategic Objectives
-
Technical Excellence - Achieve <7 second VM boot time - Maintain 99.9% uptime for active sessions - Zero memory leaks or security vulnerabilities
-
User Experience - One-click setup and activation - Intuitive UI requiring no technical knowledge - Automatic recovery from failures
-
Market Penetration - Establish presence in 50+ countries - Build partnerships with privacy advocacy groups - Achieve industry recognition for innovation
-
Sustainable Growth - Develop recurring revenue model - Build community of contributors - Establish enterprise offerings
2.4 Product Principles
- Privacy First: No logs, no tracking, no compromise
- Simplicity: Complex technology, simple interface
- Transparency: Open about capabilities and limitations
- Reliability: Fail-safe mechanisms at every level
- Performance: Minimal impact on system resources
3. Market Analysis & Positioning
3.1 Market Overview
The global VPN market is valued at $44.6 billion (2023) with a CAGR of 15.1%. Key drivers include: - Increasing censorship and surveillance - Growing awareness of digital privacy - Remote work proliferation - Regulatory compliance requirements
3.2 Competitive Analysis
| Competitor | Strengths | Weaknesses | HiddenRoute Advantage |
|---|---|---|---|
| NordVPN | Brand recognition, server network | Requires trust, external servers | Local processing, no trust needed |
| ExpressVPN | Speed, ease of use | Expensive, closed source | Transparent operations, one-time cost |
| Tor Browser | Free, strong anonymity | Slow, limited to browser | System-wide protection, better speed |
| Pi-hole | Ad-blocking, local | Technical setup required | One-click setup, integrated features |
3.3 Target Market Segments
Primary Segment: Privacy Advocates (40%)
- Demographics: 25-45 years, tech-savvy
- Pain Points: Don't trust VPN providers, want local control
- Value Proposition: Complete local control, no external dependencies
Secondary Segment: Censorship Circumvention (35%)
- Demographics: Journalists, activists, researchers
- Pain Points: Need reliable access to blocked content
- Value Proposition: DPI bypass, fail-safe mechanisms
Tertiary Segment: General Consumers (25%)
- Demographics: 18-65 years, privacy-aware
- Pain Points: Ads, tracking, complexity
- Value Proposition: Simple one-click privacy
3.4 Go-to-Market Strategy
- Phase 1: Direct-to-consumer via hiddenroute.com
- Phase 2: Privacy community partnerships
- Phase 3: B2B enterprise offerings
- Phase 4: OEM partnerships
4. User Personas & Journey Maps
4.1 Primary Personas
Persona 1: "Privacy Paul"
- Age: 32, Software Developer
- Location: San Francisco, USA
- Tech Level: Expert
- Goals: Complete privacy control, no third-party trust
- Pain Points: Current VPNs require trusting providers
- Journey: Research → Trial → Purchase → Advocate
Persona 2: "Journalist Jana"
- Age: 28, Investigative Journalist
- Location: Istanbul, Turkey
- Tech Level: Intermediate
- Goals: Access blocked sources, protect sources
- Pain Points: Government surveillance, site blocking
- Journey: Recommendation → Trial → Purchase → Daily Use
Persona 3: "Student Sam"
- Age: 21, University Student
- Location: Beijing, China
- Tech Level: Basic
- Goals: Access academic resources, social media
- Pain Points: Great Firewall, slow VPNs
- Journey: Friend Referral → Trial → Purchase
4.2 User Journey Map
Awareness → Consideration → Trial → Purchase → Onboarding → Daily Use → Advocacy
| | | | | | |
Website Compare Download License First Use Routine Share
Social Reviews Install Payment Configure Updates Review
Referral Features Test Activate Customize Support Refer
4.3 User Story Examples
-
As a privacy advocate, I want to route all my traffic through a local VM so that no external party can monitor my activities.
-
As a journalist, I want to quickly toggle between normal and Tor modes so that I can protect sensitive research without impacting regular browsing.
-
As a general user, I want automatic ad-blocking so that I can browse without interruptions or tracking.
-
As a system administrator, I want detailed logs and configuration options so that I can customize the solution for my organization.
-
As a mobile worker, I want automatic kill-switch protection so that my traffic never leaks if the VPN fails.
5. System Architecture
5.1 High-Level Architecture
┌─────────────────────────────────────────────────────────────┐
│ HiddenRoute System │
├─────────────────────────────────────────────────────────────┤
│ Presentation Layer │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Qt GUI │ │ Tray Icon │ │ Web Config UI │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Application Layer │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │License Mgr │ │Network Mgr │ │ Update Service│ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Core Services Layer │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ VBox API │ │Kill Switch │ │Heartbeat Svc │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Virtualization Layer │
│ ┌─────────────────────────────────────────────────┐ │
│ │ OpenWrt VM (512MB RAM, 1 CPU) │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌─────────┐ │ │
│ │ │ Zapret │ │ Tor │ │AdBlock │ │ OpenVPN │ │ │
│ │ └────────┘ └────────┘ └────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Network Layer │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │Bridge Adapter│ │ DNS Resolver │ │ WFP Driver │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
└─────────────────────────────────────────────────────────────┘
5.2 Component Details
5.2.1 Presentation Layer
- Qt GUI Framework: Cross-platform UI with native look
- System Tray Integration: Minimal UI footprint
- Web Configuration: Advanced settings via local web server
5.2.2 Application Layer
- License Manager: HWID validation, trial management
- Network Manager: Adapter configuration, routing tables
- Update Service: Secure binary and VM image updates
5.2.3 Core Services
- VirtualBox API Wrapper: Dynamic loading of VBoxC.dll
- Kill Switch Service: Windows Filtering Platform integration
- Heartbeat Service: Session management and monitoring
5.2.4 Virtualization Layer
- OpenWrt Base: Lightweight Linux for routing
- Zapret DPI Bypass: Advanced packet manipulation
- Tor Integration: SOCKS5 proxy on port 9050
- Luci-Adblock: Comprehensive ad filtering
5.3 Data Flow
-
Startup Sequence
User Launch → License Check → VM Start → Network Config → Ready -
Traffic Flow (DPI Mode)
Application → Windows TCP/IP → Bridge → OpenWrt → Zapret → Internet -
Traffic Flow (Tor Mode)
Application → Windows TCP/IP → Bridge → OpenWrt → Tor → Exit Node
5.4 Network Architecture
┌─────────────┐ ┌─────────────────┐ ┌──────────────┐
│ Host Apps │────▶│ Virtual Bridge │────▶│ OpenWrt VM │
└─────────────┘ └─────────────────┘ └──────┬───────┘
│
┌─────────────────────────┼─────────────┐
│ ▼ │
┌──────┴──────┐ ┌──────────────┐ │
│ Zapret │ │ Tor │ │
│ DPI Bypass │ │ SOCKS5:9050 │ │
└──────┬──────┘ └──────┬───────┘ │
│ │ │
└─────────────┬───────────┘ │
▼ │
┌──────────────┐ │
│ Internet │◀────────────────┘
└──────────────┘
6. Functional Requirements
6.1 Core Functionality
FR-001: Installation & Setup
- Priority: P0 (Critical)
- Description: Silent installation of all components
- Acceptance Criteria:
- Single setup.exe installs all components
- No user interaction required during install
- VirtualBox installed silently
- VM image extracted and configured
- Desktop shortcut created
- Total installation time < 3 minutes
FR-002: License Management
- Priority: P0 (Critical)
- Description: HWID-based licensing with trial
- Acceptance Criteria:
- Generate unique HWID per device
- 3-day trial automatically activated
- License validation with server
- Offline grace period of 7 days
- Multiple device detection and blocking
- Premium license activation
FR-003: VM Lifecycle Management
- Priority: P0 (Critical)
- Description: Start, stop, and monitor OpenWrt VM
- Acceptance Criteria:
- VM starts in < 7 seconds
- Headless operation (no VM window)
- Automatic restart on crash
- Resource limits enforced (512MB RAM, 1 CPU)
- Health monitoring every 30 seconds
FR-004: Network Configuration
- Priority: P0 (Critical)
- Description: Automatic network routing setup
- Acceptance Criteria:
- Detect active network adapter
- Configure VM bridge without conflicts
- Update host routing tables
- Modify DNS settings
- Preserve original settings
- Rollback on failure
FR-005: DPI Bypass Mode
- Priority: P0 (Critical)
- Description: Activate Zapret DPI bypass
- Acceptance Criteria:
- One-click activation
- Status indicator in UI
- Bypass effectiveness testing
- Automatic rule updates
- Fallback mechanisms
FR-006: Ad-Blocking
- Priority: P1 (High)
- Description: Integrated ad and tracker blocking
- Acceptance Criteria:
- Luci-Adblock integration
- Default blocklists included
- Custom blocklist support
- Whitelist functionality
- Hourly blocklist updates
FR-007: Tor Integration
- Priority: P1 (High)
- Description: Optional Tor proxy mode
- Acceptance Criteria:
- Requires DPI mode active
- SOCKS5 proxy on 127.0.0.1:9050
- Firefox automatic configuration
- Tor circuit information display
- New identity function
FR-008: Kill Switch
- Priority: P0 (Critical)
- Description: Block traffic if VPN fails
- Acceptance Criteria:
- Windows Filtering Platform integration
- Immediate traffic blocking
- No DNS leaks
- Whitelist for local traffic
- Persistent across reboots
FR-009: Auto-Update System
- Priority: P1 (High)
- Description: Secure application updates
- Acceptance Criteria:
- Check updates every 24 hours
- Delta updates supported
- Signature verification
- Rollback capability
- Update via Tor option
FR-010: Heartbeat & Session Management
- Priority: P0 (Critical)
- Description: Active session monitoring
- Acceptance Criteria:
- Heartbeat every 10 minutes
- Multi-device session blocking
- Automatic logout after 15 min idle
- Session recovery mechanisms
- Server synchronization
6.2 User Interface Requirements
UI-001: Main Window
- Components:
- Circular ON/OFF toggle button
- DPI+Adblock mode switch
- Tor mode switch
- Status indicators
- Settings button
- Help button
UI-002: System Tray
- Components:
- Status icon (changes based on mode)
- Right-click context menu
- Quick toggle options
- Exit option
UI-003: Settings Panel
- Components:
- General settings tab
- Network settings tab
- Advanced settings tab
- About/License tab
- Update settings
UI-004: Login Screen
- Components:
- Username/email field
- Password field
- Remember me checkbox
- Forgot password link
- Create account button
6.3 API Requirements
API-001: License Server API
POST /api/v1/license/validate
{
"hwid": "string",
"username": "string",
"password": "string"
}
Response:
{
"valid": boolean,
"type": "trial|premium",
"expires": "ISO8601",
"features": ["dpi", "tor", "adblock"]
}
API-002: Heartbeat API
POST /api/v1/heartbeat
{
"session_id": "string",
"hwid": "string",
"timestamp": "ISO8601"
}
Response:
{
"status": "active|expired|blocked",
"message": "string"
}
API-003: Update Check API
GET /api/v1/update/check?version=2.0.0&platform=windows
Response:
{
"update_available": boolean,
"version": "string",
"download_url": "string",
"signature": "string",
"changelog": "string"
}
7. Technical Requirements
7.1 Development Environment
7.1.1 Programming Languages
- Core Application: C++17/20
- UI Framework: Qt 6.8+ (C++)
- Scripting: PowerShell, Batch
- VM Configuration: Shell scripts
- Web Config UI: HTML5/CSS3/JavaScript
7.1.2 Build System
- Primary: CMake 3.20+
- Compiler: MSVC 2022 (Windows) or MinGW (Windows)
- Package Manager: Conan or vcpkg
- CI/CD: GitLab CI/GitHub Actions
7.1.3 Development Tools
- IDE: Visual Studio 2022 / Qt Creator
- Version Control: Git
- Code Analysis: PVS-Studio, Clang-Tidy
- Documentation: Doxygen
- Testing: Google Test, Qt Test
7.2 Dependencies
7.2.1 Core Dependencies
# CMakeLists.txt dependencies
find_package(Qt6 REQUIRED COMPONENTS Core Widgets Network)
find_package(OpenSSL REQUIRED)
find_package(Boost REQUIRED COMPONENTS system filesystem)
# Third-party libraries
add_subdirectory(libs/json) # nlohmann/json
add_subdirectory(libs/spdlog) # Logging
add_subdirectory(libs/cryptopp) # Cryptography
7.2.2 System Dependencies
- VirtualBox: 7.0+ (bundled)
- Windows SDK: 10.0.19041+
- Visual C++ Redistributables: 2022
- .NET Framework: 4.8 (for installer)
7.3 Performance Requirements
7.3.1 Application Performance
| Metric | Requirement | Measurement Method |
|---|---|---|
| Startup Time | < 2 seconds | Timer from launch to UI ready |
| Memory Usage | < 100 MB (idle) | Windows Performance Monitor |
| CPU Usage | < 2% (idle) | Task Manager measurement |
| VM Boot Time | < 7 seconds | Timer from start to ready |
| Toggle Response | < 1 second | UI interaction to state change |
7.3.2 Network Performance
| Metric | Requirement | Measurement Method |
|---|---|---|
| Latency Overhead | < 10ms | Ping comparison with/without |
| Throughput | > 90% of line speed | Speed test comparison |
| DNS Resolution | < 50ms | DNS query timing |
| Connection Stability | 99.9% uptime | Monitoring over 24h |
7.4 Scalability Requirements
7.4.1 User Scalability
- Support 100,000+ concurrent users
- License server horizontal scaling
- CDN for update distribution
- Regional server deployment
7.4.2 Technical Scalability
- Modular architecture for feature additions
- Plugin system for future extensions
- API versioning for compatibility
- Database sharding for user data
7.5 Integration Requirements
7.5.1 VirtualBox Integration
// Dynamic VBoxC.dll loading
class VBoxAPIWrapper {
private:
HMODULE hVBoxC;
IVirtualBoxClient* client;
IVirtualBox* vbox;
public:
bool Initialize() {
hVBoxC = LoadLibrary("VBoxC.dll");
if (!hVBoxC) return false;
// Get COM interfaces
auto pfnClientInit = (PFN_VirtualBoxClientInit)
GetProcAddress(hVBoxC, "VirtualBoxClientInit");
return SUCCEEDED(pfnClientInit(&client));
}
bool StartVM(const std::wstring& vmName) {
// Implementation
}
};
7.5.2 Windows Network Integration
// Windows Filtering Platform for Kill Switch
class KillSwitch {
private:
HANDLE engineHandle;
UINT64 filterId;
public:
bool Enable() {
FWPM_SESSION session = {0};
session.displayData.name = L"HiddenRoute Kill Switch";
DWORD result = FwpmEngineOpen(
nullptr,
RPC_C_AUTHN_DEFAULT,
nullptr,
&session,
&engineHandle
);
return (result == ERROR_SUCCESS);
}
};
7.6 Platform Requirements
7.6.1 Windows Support
- Minimum: Windows 10 version 1809 (x64)
- Recommended: Windows 11 22H2+
- Architecture: x64 only
- Privileges: Administrator for installation
- Storage: 500 MB free space
7.6.2 Future Platform Support
- Linux: Ubuntu 20.04+, Fedora 35+
- macOS: 11.0 Big Sur+
- Android: 8.0+ (future roadmap)
8. Security & Compliance Framework
8.1 Security Architecture
8.1.1 Defense in Depth Strategy
Layer 1: Application Security
├── Code signing with EV certificate
├── Anti-debugging and anti-tampering
├── Memory protection (ASLR, DEP)
└── Secure update mechanism
Layer 2: Communication Security
├── TLS 1.3 for all API calls
├── Certificate pinning
├── Perfect forward secrecy
└── Encrypted configuration storage
Layer 3: VM Security
├── Isolated network namespace
├── Minimal attack surface
├── Regular security updates
└── Hardened OpenWrt build
Layer 4: Data Security
├── No logging policy
├── Encrypted license storage
├── Secure credential handling
└── Memory wiping after use
8.1.2 Threat Model
| Threat | Impact | Likelihood | Mitigation |
|---|---|---|---|
| License cracking | High | High | HWID binding, obfuscation, server validation |
| VM escape | Critical | Low | Regular VirtualBox updates, minimal VM |
| Network interception | High | Medium | TLS, certificate pinning, Tor option |
| DPI detection | Medium | High | Regular Zapret updates, multiple methods |
| Kill switch bypass | High | Low | WFP deep integration, multiple checks |
8.2 Compliance Requirements
8.2.1 GDPR Compliance
- Data Minimization: Collect only HWID and email
- Right to Erasure: Account deletion API
- Data Portability: Export user data
- Privacy by Design: No-logs architecture
- Consent: Clear opt-in for any data collection
8.2.2 Security Standards
- DISA STIG: Application security checklist
- CERT C++: Secure coding guidelines
- OWASP: Web security for config UI
- ISO 27001: Information security management
8.3 Security Implementation
8.3.1 License Protection
class LicenseManager {
private:
std::string GenerateHWID() {
// Combine multiple hardware identifiers
auto cpuId = GetCPUID();
auto diskSerial = GetDiskSerial();
auto motherboardId = GetMotherboardID();
// Hash combination
SHA256 hasher;
hasher.Update(cpuId);
hasher.Update(diskSerial);
hasher.Update(motherboardId);
return hasher.Final();
}
bool ValidateLicense(const License& license) {
// Verify signature
if (!VerifySignature(license)) return false;
// Check HWID
if (license.hwid != GenerateHWID()) return false;
// Check expiration
if (license.expires < std::chrono::system_clock::now())
return false;
return true;
}
};
8.3.2 Anti-Debugging
class AntiDebug {
public:
static bool IsDebuggerPresent() {
// Multiple detection methods
if (::IsDebuggerPresent()) return true;
// Check PEB
BOOL isDebugged = FALSE;
CheckRemoteDebuggerPresent(GetCurrentProcess(), &isDebugged);
if (isDebugged) return true;
// Timing checks
auto start = std::chrono::high_resolution_clock::now();
// Critical operation
auto end = std::chrono::high_resolution_clock::now();
if (end - start > expected_duration * 10) return true;
return false;
}
};
8.4 Privacy Protection
8.4.1 No-Logs Implementation
- Memory-only operations: No disk writes for traffic
- Disabled VM logging: OpenWrt configured for no logs
- Encrypted temp files: If needed, encrypted and wiped
- Session data purge: Automatic cleanup on exit
8.4.2 DNS Leak Prevention
class DNSLeakPrevention {
private:
bool BlockSystemDNS() {
// Add WFP rules to block all DNS except through VM
FWPM_FILTER filter = {0};
filter.displayData.name = L"Block System DNS";
filter.action.type = FWP_ACTION_BLOCK;
filter.layerKey = FWPM_LAYER_ALE_AUTH_CONNECT_V4;
filter.subLayerKey = HIDDENROUTE_SUBLAYER;
// Add conditions for port 53
FWPM_FILTER_CONDITION conditions[2] = {0};
conditions[0].fieldKey = FWPM_CONDITION_IP_REMOTE_PORT;
conditions[0].matchType = FWP_MATCH_EQUAL;
conditions[0].conditionValue.type = FWP_UINT16;
conditions[0].conditionValue.uint16 = 53;
filter.filterCondition = conditions;
filter.numFilterConditions = 1;
return FwpmFilterAdd(engineHandle, &filter, nullptr, nullptr)
== ERROR_SUCCESS;
}
};
9. User Interface Design
9.1 Design Principles
- Minimalist: Clean, uncluttered interface
- Intuitive: Self-explanatory controls
- Responsive: Immediate visual feedback
- Accessible: WCAG 2.1 AA compliance
- Consistent: Unified design language
9.2 UI Components
9.2.1 Main Window Design
┌─────────────────────────────────────┐
│ HiddenRoute ⚙ ? │
├─────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ │ │
│ │ OFF │ │
│ │ │ │
│ └─────────────┘ │
│ │
│ ┌───────────────────────────────┐ │
│ │ 🛡️ DPI + Adblock [ ] │ │
│ └───────────────────────────────┘ │
│ │
│ ┌───────────────────────────────┐ │
│ │ 🔐 Tor Mode [ ] │ │
│ └───────────────────────────────┘ │
│ │
│ Status: Disconnected │
│ IP: ---.---.---.--- │
│ │
└─────────────────────────────────────┘
9.2.2 Settings Window
┌─────────────────────────────────────┐
│ Settings X │
├─────────────────────────────────────┤
│ [General][Network][Advanced][About] │
├─────────────────────────────────────┤
│ General Settings │
│ ┌─────────────────────────────┐ │
│ │ ☑ Start with Windows │ │
│ │ ☑ Start minimized │ │
│ │ ☑ Show notifications │ │
│ │ ☑ Auto-connect on startup │ │
│ └─────────────────────────────┘ │
│ │
│ Kill Switch │
│ ┌─────────────────────────────┐ │
│ │ ☑ Enable kill switch │ │
│ │ ☑ Block on startup │ │
│ └─────────────────────────────┘ │
│ │
│ [ Save ] [ Cancel ] │
└─────────────────────────────────────┘
9.3 Visual Design
9.3.1 Color Palette
:root {
--primary-color: #2E86AB; /* Trust Blue */
--secondary-color: #A23B72; /* Security Purple */
--success-color: #70C1B3; /* Connected Green */
--warning-color: #F18F01; /* Warning Orange */
--danger-color: #C73E1D; /* Disconnected Red */
--background: #1A1A2E; /* Dark Background */
--surface: #16213E; /* Card Surface */
--text-primary: #EAEAEA; /* Primary Text */
--text-secondary: #B4B4B4; /* Secondary Text */
}
9.3.2 Typography
/* System Font Stack for Native Feel */
body {
font-family: -apple-system, BlinkMacSystemFont,
'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
}
/* Font Hierarchy */
.heading-1 { font-size: 24px; font-weight: 600; }
.heading-2 { font-size: 18px; font-weight: 500; }
.body-text { font-size: 14px; font-weight: 400; }
.caption { font-size: 12px; font-weight: 400; }
9.4 Animations & Transitions
9.4.1 Connection Animation
.connection-button {
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}
.connection-button.connecting {
animation: pulse 1.5s infinite;
}
@keyframes pulse {
0% { transform: scale(1); opacity: 1; }
50% { transform: scale(1.05); opacity: 0.8; }
100% { transform: scale(1); opacity: 1; }
}
9.4.2 Status Indicators
.status-indicator {
width: 8px;
height: 8px;
border-radius: 50%;
transition: background-color 0.3s ease;
}
.status-indicator.connected {
background-color: var(--success-color);
box-shadow: 0 0 10px var(--success-color);
}
.status-indicator.disconnected {
background-color: var(--danger-color);
}
9.5 Responsive Design
9.5.1 Window Scaling
- Minimum Size: 400x500 pixels
- Maximum Size: 600x800 pixels
- DPI Awareness: Support 100% to 200% scaling
- Font Scaling: Respect system font size
9.5.2 Adaptive Layouts
// Qt Responsive Layout
void MainWindow::resizeEvent(QResizeEvent* event) {
int width = event->size().width();
if (width < 450) {
// Compact layout
ui->statusLabel->setVisible(false);
ui->ipLabel->setVisible(false);
} else {
// Normal layout
ui->statusLabel->setVisible(true);
ui->ipLabel->setVisible(true);
}
}
10. Development Roadmap
10.1 Phase 1: MVP (Months 1-3)
Goal: Basic functional product with core features
Sprint 1-2: Foundation
- [ ] Project setup and architecture
- [ ] VirtualBox API integration
- [ ] Basic VM management
- [ ] Network configuration module
Sprint 3-4: Core Features
- [ ] License management system
- [ ] DPI bypass implementation
- [ ] Kill switch development
- [ ] Basic UI with Qt
Sprint 5-6: Integration
- [ ] Silent installer creation
- [ ] Auto-update mechanism
- [ ] Heartbeat service
- [ ] Initial testing suite
Deliverables: - Working Windows application - Basic DPI bypass functionality - License validation
10.2 Phase 2: Enhancement (Months 4-6)
Goal: Full feature set and polish
Sprint 7-8: Advanced Features
- [ ] Tor integration
- [ ] Advanced ad-blocking
- [ ] DNS leak prevention
- [ ] Settings management
Sprint 9-10: UI/UX Polish
- [ ] Professional UI design
- [ ] Animations and transitions
- [ ] System tray integration
- [ ] Notification system
Sprint 11-12: Quality Assurance
- [ ] Comprehensive testing
- [ ] Performance optimization
- [ ] Security audit
- [ ] Documentation
Deliverables: - Feature-complete application - Professional UI - Comprehensive documentation
10.3 Phase 3: Launch Preparation (Months 7-8)
Goal: Market-ready product
Sprint 13-14: Infrastructure
- [ ] License server deployment
- [ ] Update server setup
- [ ] Website development
- [ ] Payment integration
Sprint 15-16: Beta Testing
- [ ] Closed beta program
- [ ] Bug fixes and optimization
- [ ] User feedback integration
- [ ] Final security audit
Deliverables: - Production infrastructure - Beta-tested application - Launch materials
10.4 Phase 4: Post-Launch (Months 9-12)
Goal: Growth and expansion
Quarter 1: Stabilization
- [ ] Monitor and fix issues
- [ ] User support system
- [ ] Performance monitoring
- [ ] First major update
Quarter 2: Platform Expansion
- [ ] Linux version development
- [ ] macOS planning
- [ ] Mobile strategy
- [ ] Enterprise features
Deliverables: - Stable Windows product - Linux alpha version - Expansion roadmap
10.5 Long-term Roadmap (Year 2+)
Year 2 Goals
-
Multi-platform Support - Linux stable release - macOS beta - Android alpha
-
Enterprise Features - Centralized management - Bulk licensing - Custom configurations - Priority support
-
Advanced Features - Multiple VM configurations - Custom routing rules - API for third-party integration - Browser extensions
Year 3 Vision
-
Market Leadership - 200,000+ active users - Industry recognition - Strategic partnerships
-
Technical Innovation - AI-powered DPI evasion - Quantum-resistant encryption - Decentralized infrastructure
11. Testing & Quality Assurance
11.1 Testing Strategy
11.1.1 Testing Pyramid
┌─────┐
/ E2E \ 5% - End-to-end tests
/─────────\
/ Integration\ 15% - Integration tests
/───────────────\
/ Unit Tests \80% - Unit tests
/───────────────────\
11.1.2 Test Categories
- Unit Tests: Individual component testing
- Integration Tests: Component interaction
- System Tests: Full application testing
- Performance Tests: Speed and resource usage
- Security Tests: Vulnerability assessment
- Usability Tests: User experience validation
11.2 Test Plans
11.2.1 Unit Test Coverage
// Example: License Manager Tests
TEST(LicenseManagerTest, ValidateValidLicense) {
LicenseManager mgr;
License license{
.hwid = "test-hwid",
.expires = future_date,
.signature = valid_signature
};
EXPECT_TRUE(mgr.ValidateLicense(license));
}
TEST(LicenseManagerTest, RejectExpiredLicense) {
LicenseManager mgr;
License license{
.hwid = "test-hwid",
.expires = past_date,
.signature = valid_signature
};
EXPECT_FALSE(mgr.ValidateLicense(license));
}
11.2.2 Integration Test Scenarios
-
VM Lifecycle - Start VM → Verify running - Stop VM → Verify stopped - Restart VM → Verify recovery
-
Network Configuration - Apply settings → Verify routing - Rollback → Verify restoration - Kill switch → Verify blocking
-
License Flow - Login → Validate → Activate - Heartbeat → Session management - Expiry → Deactivation
11.3 Performance Testing
11.3.1 Performance Benchmarks
| Test Case | Target | Method |
|---|---|---|
| Application Startup | < 2s | Automated timer |
| VM Boot Time | < 7s | Integration test |
| Memory Usage (Idle) | < 100MB | Performance monitor |
| CPU Usage (Active) | < 10% | Resource monitoring |
| Network Throughput | > 90% baseline | Speed test comparison |
11.3.2 Load Testing
# Load test script example
import asyncio
import aiohttp
async def simulate_heartbeat(session, user_id):
url = "https://api.hiddenroute.com/v1/heartbeat"
data = {
"user_id": user_id,
"timestamp": datetime.now().isoformat()
}
async with session.post(url, json=data) as response:
return await response.json()
async def load_test():
async with aiohttp.ClientSession() as session:
tasks = []
for i in range(10000): # 10k concurrent users
task = simulate_heartbeat(session, f"user_{i}")
tasks.append(task)
results = await asyncio.gather(*tasks)
# Analyze results
11.4 Security Testing
11.4.1 Security Test Cases
-
Authentication Security - SQL injection attempts - Brute force protection - Session hijacking prevention
-
License Protection - Reverse engineering resistance - License bypass attempts - HWID spoofing detection
-
Network Security - DNS leak testing - Kill switch effectiveness - Traffic interception attempts
11.4.2 Penetration Testing
- Internal Testing: Monthly security scans
- External Audit: Quarterly third-party assessment
- Bug Bounty: Continuous community testing
11.5 Quality Metrics
11.5.1 Code Quality Metrics
| Metric | Target | Tool |
|---|---|---|
| Code Coverage | > 80% | Coverage.py |
| Cyclomatic Complexity | < 10 | SonarQube |
| Technical Debt | < 5% | SonarQube |
| Duplication | < 3% | CPD |
11.5.2 Release Quality Gates
-
Pre-Alpha - All unit tests passing - No critical bugs - Core features functional
-
Alpha - 70% test coverage - No major bugs - UI functional
-
Beta - 80% test coverage - Performance targets met - Security audit passed
-
Release - All tests passing - Zero critical issues - Documentation complete
12. Deployment & Operations
12.1 Deployment Architecture
12.1.1 Infrastructure Overview
┌─────────────────────────────────────────────────────┐
│ Production Environment │
├─────────────────────────────────────────────────────┤
│ CDN Layer (CloudFlare) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Static Assets│ │Binary Updates│ │ VM Images │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────┤
│ Application Layer (AWS/Azure) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ API Gateway │ │Load Balancer │ │ WAF │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────┤
│ Service Layer (Kubernetes) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │License API │ │Heartbeat API │ │ Update API │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────┤
│ Data Layer │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │PostgreSQL │ │ Redis Cache │ │ S3 Storage │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────┘
12.1.2 Deployment Pipeline
# .gitlab-ci.yml
stages:
- build
- test
- security
- package
- deploy
build:windows:
stage: build
script:
- cmake -B build -G "Visual Studio 17 2022"
- cmake --build build --config Release
artifacts:
paths:
- build/Release/
test:unit:
stage: test
script:
- ctest --test-dir build -C Release
coverage: '/Total Coverage: \d+\%/'
security:scan:
stage: security
script:
- pvs-studio-analyzer analyze
- owasp-dependency-check
package:installer:
stage: package
script:
- iscc setup/installer.iss
- signtool sign /f cert.pfx /p $CERT_PASSWORD setup.exe
deploy:production:
stage: deploy
script:
- aws s3 cp setup.exe s3://releases/
- aws cloudfront create-invalidation
only:
- tags
12.2 Release Management
12.2.1 Version Numbering
MAJOR.MINOR.PATCH-CHANNEL
2.1.0-stable (Production release)
2.1.1-beta (Beta channel)
2.2.0-alpha (Alpha channel)
2.2.0-rc1 (Release candidate)
12.2.2 Release Process
- Development Complete → Feature freeze
- Testing Phase → QA validation (1 week)
- Release Candidate → Beta testing (1 week)
- Production Release → Gradual rollout
- Post-Release → Monitor and hotfix
12.3 Monitoring & Observability
12.3.1 Application Metrics
// Metrics collection example
class MetricsCollector {
public:
void RecordConnectionTime(double seconds) {
prometheus::Histogram::Builder()
.Name("hiddenroute_connection_duration_seconds")
.Help("Time to establish VPN connection")
.Register(*registry)
.Add({})
.Observe(seconds);
}
void RecordActiveUsers(int count) {
prometheus::Gauge::Builder()
.Name("hiddenroute_active_users")
.Help("Number of active users")
.Register(*registry)
.Add({})
.Set(count);
}
};
12.3.2 Monitoring Stack
- Metrics: Prometheus + Grafana
- Logging: ELK Stack (Elasticsearch, Logstash, Kibana)
- Tracing: Jaeger
- Alerting: PagerDuty
- Status Page: Statuspage.io
12.4 Operational Procedures
12.4.1 Incident Response
1. Detection (< 5 min)
└─> Automated alerts via monitoring
2. Triage (< 15 min)
└─> On-call engineer assessment
3. Response (< 30 min)
└─> Implement fix or workaround
4. Resolution (< 2 hours)
└─> Deploy patch if needed
5. Post-mortem (< 48 hours)
└─> Document and improve
12.4.2 Backup & Recovery
- Database: Daily automated backups, 30-day retention
- Configuration: Version controlled in Git
- Binary Archives: All releases stored in S3
- Recovery Time Objective (RTO): < 1 hour
- Recovery Point Objective (RPO): < 24 hours
12.5 Support Infrastructure
12.5.1 Support Tiers
-
Tier 1: Self-Service - Knowledge base - FAQ section - Community forum
-
Tier 2: Email Support - 24-hour response time - Ticket system - Standard issues
-
Tier 3: Priority Support - 1-hour response time - Phone/chat support - Enterprise customers
12.5.2 Support Tools
- Ticketing: Zendesk
- Knowledge Base: Confluence
- Community: Discourse
- Remote Support: TeamViewer
- Diagnostics: Built-in log collection
13. Business Model & Monetization
13.1 Revenue Model
13.1.1 Pricing Tiers
| Plan | Monthly | Features | Target |
|---|---|---|---|
| Free Trial | $0 | 3 days, all features | New users |
| Basic | $4.99 | DPI + Adblock | Casual users |
| Pro | $9.99 | + Tor, priority support | Power users |
| Teams | $7.99/user | Central management | Small business |
| Enterprise | Custom | SLA, dedicated support | Large orgs |
13.1.2 Revenue Projections
Year 1: $100K - $200K
- 10,000 users × 20% conversion × $7 avg = $14K/month
Year 2: $500K - $1M
- 50,000 users × 25% conversion × $8 avg = $100K/month
Year 3: $2M - $5M
- 200,000 users × 30% conversion × $9 avg = $540K/month
13.2 Cost Structure
13.2.1 Infrastructure Costs
| Component | Monthly Cost | Annual |
|---|---|---|
| AWS/Azure hosting | $2,000 | $24,000 |
| CDN (CloudFlare) | $500 | $6,000 |
| Monitoring tools | $300 | $3,600 |
| Code signing cert | $50 | $600 |
| Total | $2,850 | $34,200 |
13.2.2 Operational Costs
| Component | Monthly Cost | Annual |
|---|---|---|
| Development (2 FTE) | $20,000 | $240,000 |
| Support (1 FTE) | $5,000 | $60,000 |
| Marketing | $2,000 | $24,000 |
| Legal/Compliance | $1,000 | $12,000 |
| Total | $28,000 | $336,000 |
13.3 Customer Acquisition
13.3.1 Marketing Channels
-
Organic Search (40%) - SEO-optimized website - Technical blog content - Privacy guides
-
Community Marketing (30%) - Privacy forums - Reddit communities - Open source contributions
-
Referral Program (20%) - 30% commission for affiliates - User referral rewards - Influencer partnerships
-
Paid Advertising (10%) - Google Ads (targeted) - Privacy-focused publications - Podcast sponsorships
13.3.2 Conversion Funnel
Website Visit (100%)
↓
Download (25%)
↓
Install (20%)
↓
Trial Activation (15%)
↓
Purchase (3-5%)
↓
Retention (80% monthly)
13.4 Partnerships
13.4.1 Strategic Partners
-
Privacy Advocates - Electronic Frontier Foundation - Privacy International - Local digital rights groups
-
Technical Partners - VirtualBox (Oracle) - OpenWrt community - Security audit firms
-
Distribution Partners - Software bundlers - Privacy-focused VPS providers - Cryptocurrency services
13.4.2 Revenue Sharing
- Affiliate Program: 30% lifetime commission
- Reseller Program: 40% discount for bulk
- White Label: Custom pricing for OEM
13.5 Financial Projections
13.5.1 Break-even Analysis
Fixed Costs: $30,000/month
Variable Costs: $0.50/user/month
Price: $7/user/month
Break-even: 4,615 paying users
13.5.2 5-Year Financial Model
| Year | Users | Revenue | Costs | Profit |
|---|---|---|---|---|
| 1 | 10K | $168K | $370K | -$202K |
| 2 | 50K | $1.2M | $450K | $750K |
| 3 | 200K | $6.5M | $800K | $5.7M |
| 4 | 500K | $18M | $1.5M | $16.5M |
| 5 | 1M | $42M | $3M | $39M |
14. Risk Assessment & Mitigation
14.1 Technical Risks
14.1.1 Risk Matrix
| Risk | Probability | Impact | Mitigation Strategy |
|---|---|---|---|
| VirtualBox API changes | Medium | High | Abstract API layer, version pinning |
| Windows update breaks app | High | Medium | Automated testing, quick patches |
| DPI detection methods evolve | High | High | Modular bypass methods, rapid updates |
| Performance degradation | Medium | Medium | Continuous monitoring, optimization |
| Security vulnerability | Low | Critical | Security audits, bug bounty program |
14.1.2 Technical Risk Mitigation
- API Stability ```cpp // Abstract VirtualBox API class IVMProvider { public: virtual bool StartVM(const std::string& name) = 0; virtual bool StopVM(const std::string& name) = 0; };
class VBoxProvider : public IVMProvider { // VirtualBox-specific implementation };
class QemuProvider : public IVMProvider { // Future alternative implementation }; ```
- Compatibility Testing - Automated testing on multiple Windows versions - Beta channel for early testing - Gradual rollout with killswitch
14.2 Business Risks
14.2.1 Market Risks
| Risk | Impact | Mitigation |
|---|---|---|
| Competitor with better features | High | Continuous innovation, user feedback |
| Market saturation | Medium | Differentiation, niche markets |
| Economic downturn | Medium | Freemium model, essential service |
| Regulatory changes | High | Legal compliance, adaptability |
14.2.2 Financial Risks
-
Cash Flow - Mitigation: 6-month runway, revenue diversification
-
Customer Churn - Mitigation: Excellent support, continuous improvement
-
Infrastructure Costs - Mitigation: Usage-based scaling, cost optimization
14.3 Legal & Compliance Risks
14.3.1 Regulatory Landscape
| Jurisdiction | Risk Level | Compliance Strategy |
|---|---|---|
| USA | Low | Standard business compliance |
| EU | Medium | GDPR compliance, data minimization |
| China | High | Avoid direct operations |
| Russia | High | No official presence |
14.3.2 Legal Mitigation
-
Terms of Service - Clear usage guidelines - Liability limitations - Prohibited activities
-
Privacy Policy - Transparent data handling - User rights clearly stated - Regular updates
-
Export Controls - Encryption compliance - Restricted country list - Legal counsel consultation
14.4 Operational Risks
14.4.1 Operational Risk Matrix
| Risk | Severity | Mitigation |
|---|---|---|
| Key developer leaves | High | Documentation, knowledge sharing |
| Infrastructure failure | Medium | Multi-region deployment, backups |
| Support overload | Medium | Self-service options, automation |
| Update server compromise | Critical | Code signing, secure pipeline |
14.4.2 Business Continuity Plan
-
Disaster Recovery - Automated backups - Multi-region failover - Incident response team
-
Knowledge Management - Comprehensive documentation - Cross-training - External consultants
14.5 Security Risks
14.5.1 Threat Modeling
┌─────────────────────────────────────┐
│ Threat Actors │
├─────────────────────────────────────┤
│ Script Kiddies │ Low Impact │
│ Crackers │ Medium Impact │
│ State Actors │ High Impact │
│ Competitors │ Medium Impact │
└─────────────────────────────────────┘
14.5.2 Security Controls
-
Application Security - Code obfuscation - Anti-tampering checks - Secure communication
-
Infrastructure Security - Regular penetration testing - Security monitoring - Incident response plan
15. Project Directory Structure
15.1 Complete Project Structure
hiddenroute/
├── .github/ # GitHub specific files
│ ├── workflows/ # GitHub Actions CI/CD
│ │ ├── build.yml # Build workflow
│ │ ├── test.yml # Test workflow
│ │ └── release.yml # Release workflow
│ ├── ISSUE_TEMPLATE/ # Issue templates
│ └── CODEOWNERS # Code ownership
│
├── build/ # Build output directory
│ ├── windows/ # Windows builds
│ ├── linux/ # Linux builds (future)
│ └── logs/ # Build logs
│
├── cmake/ # CMake configuration
│ ├── FindVirtualBox.cmake # VBox detection
│ ├── CompilerOptions.cmake # Compiler settings
│ └── Packaging.cmake # CPack configuration
│
├── configs/ # Configuration files
│ ├── app.config.json # Application config
│ ├── network.config.json # Network settings
│ └── vm.config.json # VM configuration
│
├── deployment/ # Deployment scripts
│ ├── docker/ # Docker configurations
│ │ ├── Dockerfile.api # API server image
│ │ └── docker-compose.yml # Local development
│ ├── kubernetes/ # K8s manifests
│ │ ├── api-deployment.yaml
│ │ └── ingress.yaml
│ └── terraform/ # Infrastructure as code
│ ├── main.tf
│ └── variables.tf
│
├── docs/ # Documentation
│ ├── api/ # API documentation
│ │ └── openapi.yaml # OpenAPI spec
│ ├── architecture/ # Architecture docs
│ │ ├── overview.md
│ │ └── diagrams/
│ ├── development/ # Dev guides
│ │ ├── setup.md
│ │ └── contributing.md
│ ├── user/ # User documentation
│ │ ├── installation.md
│ │ └── troubleshooting.md
│ └── PRD.md # This document
│
├── drivers/ # Windows drivers
│ ├── VBoxNetFlt/ # Network filter driver
│ ├── VBoxNetAdp/ # Network adapter driver
│ └── certificates/ # Driver signing certs
│
├── external/ # Third-party code
│ ├── vbox-sdk/ # VirtualBox SDK
│ ├── openssl/ # OpenSSL library
│ └── qt/ # Qt framework
│
├── installer/ # Installation scripts
│ ├── windows/ # Windows installer
│ │ ├── setup.iss # InnoSetup script
│ │ ├── license.rtf # EULA
│ │ └── assets/ # Installer assets
│ └── scripts/ # Helper scripts
│ ├── install-vbox.ps1
│ └── configure-vm.ps1
│
├── resources/ # Application resources
│ ├── icons/ # Application icons
│ │ ├── app.ico
│ │ └── tray/ # Tray icons
│ ├── images/ # UI images
│ ├── translations/ # i18n files
│ │ ├── en_US.ts
│ │ └── es_ES.ts
│ └── styles/ # QSS stylesheets
│ └── dark-theme.qss
│
├── scripts/ # Development scripts
│ ├── build.ps1 # Build script
│ ├── test.ps1 # Test runner
│ ├── package.ps1 # Packaging script
│ └── sign.ps1 # Code signing
│
├── src/ # Source code
│ ├── app/ # Main application
│ │ ├── main.cpp # Entry point
│ │ ├── application.cpp # App class
│ │ └── application.h
│ │
│ ├── core/ # Core functionality
│ │ ├── vbox/ # VirtualBox integration
│ │ │ ├── vbox_api.cpp
│ │ │ ├── vbox_api.h
│ │ │ ├── vm_manager.cpp
│ │ │ └── vm_manager.h
│ │ │
│ │ ├── network/ # Network management
│ │ │ ├── network_manager.cpp
│ │ │ ├── network_manager.h
│ │ │ ├── adapter_config.cpp
│ │ │ ├── dns_manager.cpp
│ │ │ └── kill_switch.cpp
│ │ │
│ │ ├── security/ # Security features
│ │ │ ├── license_manager.cpp
│ │ │ ├── hwid_generator.cpp
│ │ │ ├── encryption.cpp
│ │ │ └── anti_debug.cpp
│ │ │
│ │ └── update/ # Update system
│ │ ├── updater.cpp
│ │ ├── downloader.cpp
│ │ └── signature_verify.cpp
│ │
│ ├── gui/ # User interface
│ │ ├── windows/ # UI windows
│ │ │ ├── main_window.cpp
│ │ │ ├── main_window.h
│ │ │ ├── login_dialog.cpp
│ │ │ ├── settings_dialog.cpp
│ │ │ └── about_dialog.cpp
│ │ │
│ │ ├── widgets/ # Custom widgets
│ │ │ ├── toggle_button.cpp
│ │ │ ├── status_indicator.cpp
│ │ │ └── connection_graph.cpp
│ │ │
│ │ └── tray/ # System tray
│ │ ├── tray_icon.cpp
│ │ └── tray_menu.cpp
│ │
│ ├── services/ # Background services
│ │ ├── heartbeat/ # Heartbeat service
│ │ │ ├── heartbeat_service.cpp
│ │ │ └── session_manager.cpp
│ │ │
│ │ └── monitoring/ # Monitoring service
│ │ ├── metrics_collector.cpp
│ │ └── performance_monitor.cpp
│ │
│ └── utils/ # Utility functions
│ ├── logger.cpp # Logging utility
│ ├── config.cpp # Configuration
│ ├── crypto.cpp # Cryptography
│ └── system_info.cpp # System utilities
│
├── tests/ # Test files
│ ├── unit/ # Unit tests
│ │ ├── core/ # Core tests
│ │ │ ├── license_test.cpp
│ │ │ └── network_test.cpp
│ │ └── gui/ # GUI tests
│ │ └── main_window_test.cpp
│ │
│ ├── integration/ # Integration tests
│ │ ├── vm_lifecycle_test.cpp
│ │ └── network_config_test.cpp
│ │
│ ├── e2e/ # End-to-end tests
│ │ ├── installation_test.cpp
│ │ └── connection_test.cpp
│ │
│ └── fixtures/ # Test data
│ ├── licenses/
│ └── configs/
│
├── tools/ # Development tools
│ ├── code-generator/ # Code generation
│ ├── license-generator/ # License creation
│ └── vm-builder/ # VM image builder
│
├── vm/ # Virtual machine files
│ ├── openwrt/ # OpenWrt source
│ │ ├── config/ # Build config
│ │ ├── patches/ # Custom patches
│ │ └── scripts/ # VM scripts
│ │
│ └── images/ # Built VM images
│ ├── openwrt.vdi # Production image
│ └── openwrt-dev.vdi # Development image
│
├── .clang-format # Code formatting
├── .clang-tidy # Static analysis
├── .editorconfig # Editor config
├── .gitignore # Git ignore file
├── .gitlab-ci.yml # GitLab CI/CD
├── CMakeLists.txt # Main CMake file
├── CODE_OF_CONDUCT.md # Code of conduct
├── CONTRIBUTING.md # Contributing guide
├── LICENSE # License file
├── README.md # Project readme
└── VERSION # Version file
15.2 Key Directory Descriptions
15.2.1 Source Code Organization (src/)
- app/: Application entry point and initialization
- core/: Business logic and core functionality
- gui/: User interface components
- services/: Background services and daemons
- utils/: Shared utilities and helpers
15.2.2 Documentation (docs/)
- api/: API specifications and examples
- architecture/: System design documents
- development/: Developer guides and setup
- user/: End-user documentation
15.2.3 Testing (tests/)
- unit/: Isolated component tests
- integration/: Component interaction tests
- e2e/: Full system tests
- fixtures/: Test data and mocks
15.2.4 Virtual Machine (vm/)
- openwrt/: OpenWrt customization
- images/: Pre-built VM images
- Configuration and build scripts
15.2.5 Deployment (deployment/)
- docker/: Containerization files
- kubernetes/: Orchestration configs
- terraform/: Infrastructure as code
16. Technical Documentation Requirements
16.1 Code Documentation
16.1.1 Documentation Standards
/**
* @brief Manages the lifecycle of the OpenWrt virtual machine
*
* This class provides a high-level interface for starting, stopping,
* and monitoring the OpenWrt VM through the VirtualBox API.
*
* @note Thread-safe: All public methods are thread-safe
* @since 1.0.0
*/
class VMManager {
public:
/**
* @brief Starts the OpenWrt virtual machine
*
* @param vmName Name of the VM to start
* @param timeout Maximum time to wait for VM startup
* @return true if VM started successfully, false otherwise
* @throws VBoxException if VirtualBox API fails
*
* @code
* VMManager manager;
* if (manager.StartVM("OpenWrt", std::chrono::seconds(10))) {
* // VM is running
* }
* @endcode
*/
bool StartVM(const std::string& vmName,
std::chrono::seconds timeout = std::chrono::seconds(7));
};
16.1.2 Documentation Tools
- Doxygen: API documentation generation
- PlantUML: Diagram generation from code
- Sphinx: User documentation
- MkDocs: Markdown-based docs
16.2 API Documentation
16.2.1 REST API Documentation
openapi: 3.0.0
info:
title: HiddenRoute API
version: 1.0.0
description: License and session management API
paths:
/api/v1/license/validate:
post:
summary: Validate user license
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
hwid:
type: string
description: Hardware ID
username:
type: string
password:
type: string
responses:
200:
description: License validation result
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseResponse'
16.2.2 SDK Documentation
// Example SDK usage documentation
namespace HiddenRoute {
/**
* @example Basic Usage
* @code
* #include <hiddenroute/sdk.h>
*
* int main() {
* HiddenRoute::Client client;
*
* // Initialize the client
* if (!client.Initialize()) {
* return -1;
* }
*
* // Connect with DPI bypass
* client.Connect(ConnectionMode::DPIBypass);
*
* // Your code here
*
* // Disconnect when done
* client.Disconnect();
*
* return 0;
* }
* @endcode
*/
}
16.3 User Documentation
16.3.1 Installation Guide Structure
-
System Requirements - Hardware requirements - Software prerequisites - Supported platforms
-
Installation Steps - Download instructions - Installation process - Initial configuration
-
First Run - Account creation - License activation - Basic usage
16.3.2 Troubleshooting Guide
## Common Issues
### VM Fails to Start
**Symptoms**: Error message "Failed to start OpenWrt VM"
**Causes**:
1. Virtualization disabled in BIOS
2. Insufficient permissions
3. Port conflicts
**Solutions**:
1. Enable VT-x/AMD-V in BIOS settings
2. Run as Administrator
3. Check for conflicting applications
### Network Configuration Failed
**Symptoms**: "Failed to configure network adapter"
**Solutions**:
1. Reset network settings
2. Disable other VPN software
3. Restart Windows network service
16.4 Development Documentation
16.4.1 Architecture Decision Records (ADR)
# ADR-001: Use VirtualBox for Virtualization
## Status
Accepted
## Context
We need a virtualization solution that:
- Works on Windows without Hyper-V
- Has programmatic API
- Supports network bridging
- Is widely available
## Decision
Use Oracle VirtualBox with dynamic linking to VBoxC.dll
## Consequences
- **Positive**: Wide compatibility, good API
- **Negative**: Requires separate installation
- **Mitigation**: Bundle silent installer
16.4.2 Contributing Guidelines
# Contributing to HiddenRoute
## Code Style
- Follow the .clang-format configuration
- Use meaningful variable names
- Comment complex logic
## Pull Request Process
1. Fork the repository
2. Create feature branch
3. Write tests for new features
4. Update documentation
5. Submit pull request
## Code Review Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No security issues
- [ ] Performance impact assessed
17. Success Metrics & KPIs
17.1 Technical Metrics
17.1.1 Performance KPIs
| Metric | Target | Measurement |
|---|---|---|
| Application startup time | < 2 seconds | Automated testing |
| VM boot time | < 7 seconds | Integration tests |
| Connection establishment | < 3 seconds | User telemetry |
| Memory usage (idle) | < 100 MB | Performance monitoring |
| CPU usage (active) | < 10% | System monitoring |
| Network throughput | > 90% baseline | Speed tests |
| Crash rate | < 0.1% | Crash reporting |
| Update success rate | > 99% | Update telemetry |
17.1.2 Quality Metrics
| Metric | Target | Measurement |
|---|---|---|
| Code coverage | > 80% | CI/CD pipeline |
| Bug discovery rate | < 5/week | Issue tracking |
| Mean time to fix | < 48 hours | Issue tracking |
| Customer-reported bugs | < 10/month | Support tickets |
| Security vulnerabilities | 0 critical | Security scans |
17.2 Business Metrics
17.2.1 User Acquisition
| Metric | Target | Measurement |
|---|---|---|
| Monthly downloads | 5,000+ | Website analytics |
| Trial activations | 80% of downloads | License server |
| Conversion rate | 20% | Payment processing |
| Customer acquisition cost | < $10 | Marketing spend/conversions |
| Organic traffic | 60% | Google Analytics |
17.2.2 User Engagement
| Metric | Target | Measurement |
|---|---|---|
| Daily active users | 70% of total | Heartbeat data |
| Session duration | > 2 hours | Usage telemetry |
| Feature adoption | 80% use all features | Feature telemetry |
| Support tickets | < 5% of users | Support system |
| User satisfaction | > 4.5/5 | Surveys |
17.3 Financial Metrics
17.3.1 Revenue KPIs
| Metric | Target | Measurement |
|---|---|---|
| Monthly recurring revenue | $50,000+ (Year 2) | Payment processor |
| Average revenue per user | $7+ | Financial reports |
| Customer lifetime value | > $100 | Cohort analysis |
| Churn rate | < 5% monthly | Subscription data |
| Payment failure rate | < 2% | Payment processor |
17.3.2 Cost Metrics
| Metric | Target | Measurement |
|---|---|---|
| Infrastructure cost per user | < $0.50 | AWS/Azure billing |
| Support cost per ticket | < $5 | Time tracking |
| Development cost per feature | Track and optimize | Project management |
| Marketing ROI | > 3:1 | Campaign tracking |
17.4 Operational Metrics
17.4.1 Infrastructure KPIs
| Metric | Target | Measurement |
|---|---|---|
| API uptime | 99.9% | Monitoring tools |
| API response time | < 200ms | APM tools |
| Database query time | < 50ms | Database monitoring |
| CDN cache hit rate | > 90% | CDN analytics |
| Deployment frequency | Weekly | CI/CD pipeline |
17.4.2 Support Metrics
| Metric | Target | Measurement |
|---|---|---|
| First response time | < 24 hours | Ticket system |
| Resolution time | < 48 hours | Ticket system |
| Customer satisfaction | > 90% | Post-support survey |
| Ticket volume | < 100/week | Support dashboard |
| Self-service rate | > 70% | Support analytics |
17.5 Success Criteria
17.5.1 Year 1 Success Milestones
- [ ] 10,000+ active users
- [ ] 20% conversion rate achieved
- [ ] 99.9% uptime maintained
- [ ] Zero critical security issues
- [ ] 4.5+ star average rating
17.5.2 Long-term Success Indicators
- [ ] Market leader in local VPN solutions
- [ ] Profitable within 18 months
- [ ] Expanded to 3+ platforms
- [ ] Enterprise customer adoption
- [ ] Industry recognition and awards
18. Implementation Status
18.1 Done/Achieved
Documentation
- [x] PRD Creation - Comprehensive Product Requirements Document created (2024-12-28)
- [x] System Architecture - Detailed system design with visual diagrams
- [x] Technical Specifications - Complete technical requirements documented
- [x] Business Model - Revenue projections and pricing strategy defined
- [x] Risk Assessment - Comprehensive risk analysis and mitigation strategies
Project Setup
- [x] Directory Structure - Professional project structure defined
- [x] Documentation Framework - Comprehensive documentation structure established
- [x] Project Directories Created - Complete directory structure implemented (2024-12-28)
Core Implementation
- [x] CMake Build System - Complete CMake configuration created (2024-12-28)
- [x] Main Application Entry - main.cpp with system checks and initialization (2024-12-28)
- [x] Application Framework - Core application class structure implemented (2024-12-28)
- [x] Logging System - Thread-safe logging with file rotation (2024-12-28)
- [x] System Information Utility - Hardware and OS detection implemented (2024-12-28)
- [x] Anti-Debugging Module - Basic anti-debugging protection (2024-12-28)
- [x] Main Window GUI - Basic Qt GUI with connection toggle and modes (2024-12-28)
- [x] Utility Modules - Config management and cryptography utilities (2024-12-28)
- [x] All Source Stubs - Complete source file structure with stubs (2024-12-28)
- [x] Project Documentation - README.md and .gitignore created (2024-12-28)
18.2 To-Do/Missing
Phase 1: Foundation (Immediate Priority)
- [x] Project Initialization
- [x] Create CMake build system configuration
- [ ] Set up Git repository with proper .gitignore
-
[ ] Configure development environment
-
[ ] Core Dependencies
- [ ] Download and configure Qt 6.8+ SDK
- [ ] Set up VirtualBox SDK integration
-
[ ] Configure OpenSSL and Boost libraries
-
[x] Basic Project Structure
- [x] Create main application entry point
- [x] Implement basic logging system
- [ ] Set up configuration management
Phase 2: Core Development
- [ ] VirtualBox Integration
- [ ] Implement VBoxAPIWrapper class
- [ ] Create VM management functionality
-
[ ] Test VM lifecycle operations
-
[ ] Network Management
- [ ] Implement network configuration module
- [ ] Create DNS management system
-
[ ] Develop kill switch functionality
-
[ ] License System
- [ ] Implement HWID generation
- [ ] Create license validation logic
- [ ] Set up trial management
Phase 3: UI Development
- [ ] Qt GUI Implementation
- [ ] Create main window UI
- [ ] Implement system tray integration
- [ ] Design settings dialog
- [ ] Add login screen
Phase 4: VM and Security
- [ ] OpenWrt VM
- [ ] Configure OpenWrt build
- [ ] Install Zapret for DPI bypass
- [ ] Configure Tor integration
-
[ ] Set up Luci-Adblock
-
[ ] Security Implementation
- [ ] Implement anti-debugging measures
- [ ] Add code obfuscation
- [ ] Set up secure update mechanism
Phase 5: Testing and Deployment
- [ ] Testing Framework
- [ ] Set up Google Test
- [ ] Write unit tests
- [ ] Create integration tests
-
[ ] Implement E2E tests
-
[ ] Installer Creation
- [ ] Configure InnoSetup
- [ ] Create silent VirtualBox installer
- [ ] Build setup.exe
- [ ] Test installation process
Phase 6: Infrastructure
- [ ] Backend Services
- [ ] Set up license server
- [ ] Implement heartbeat API
-
[ ] Create update server
-
[ ] Documentation
- [ ] Write user manual
- [ ] Create developer documentation
- [ ] Prepare troubleshooting guide
18.3 Current Sprint Focus
Sprint 1 (Current): Project Foundation - Primary Goal: Set up development environment and basic project structure - Duration: 1 week - Key Deliverables: 1. Working CMake build system 2. Basic application that launches and shows a window 3. Logging system operational 4. VirtualBox SDK successfully integrated
18.4 Progress Tracking
| Component | Status | Progress | Notes |
|---|---|---|---|
| Documentation | Complete | 100% | PRD and README fully documented |
| Project Setup | Complete | 100% | Full project structure created |
| Core Development | In Progress | 40% | Basic framework implemented, needs VBox integration |
| UI Development | In Progress | 30% | Main window created, needs remaining dialogs |
| Testing | Not Started | 0% | Requires core features |
| Deployment | Not Started | 0% | Final phase |
19. Appendices
19.1 Glossary of Terms
| Term | Definition |
|---|---|
| DPI | Deep Packet Inspection - Network packet filtering that examines data contents |
| HWID | Hardware Identifier - Unique device fingerprint for licensing |
| Kill Switch | Feature that blocks all traffic if VPN connection fails |
| OPSEC | Operational Security - Practices to protect sensitive information |
| STIG | Security Technical Implementation Guide - Security configuration standards |
| VM | Virtual Machine - Isolated operating system instance |
| VPN | Virtual Private Network - Encrypted network connection |
| WFP | Windows Filtering Platform - Windows network filtering API |
| Zapret | DPI circumvention tool used in OpenWrt |
19.2 Technical Acronyms
| Acronym | Meaning |
|---|---|
| API | Application Programming Interface |
| CDN | Content Delivery Network |
| CI/CD | Continuous Integration/Continuous Deployment |
| CPU | Central Processing Unit |
| DNS | Domain Name System |
| GUI | Graphical User Interface |
| HTTP(S) | Hypertext Transfer Protocol (Secure) |
| IDE | Integrated Development Environment |
| JSON | JavaScript Object Notation |
| REST | Representational State Transfer |
| SDK | Software Development Kit |
| SQL | Structured Query Language |
| TLS | Transport Layer Security |
| UI/UX | User Interface/User Experience |
| VM | Virtual Machine |
19.3 References
19.3.1 Technical References
- VirtualBox SDK Documentation: https://www.virtualbox.org/sdkref/
- Windows Filtering Platform: https://docs.microsoft.com/en-us/windows/win32/fwp/
- Qt Documentation: https://doc.qt.io/
- OpenWrt Documentation: https://openwrt.org/docs/
- CERT C++ Coding Standard: https://wiki.sei.cmu.edu/confluence/display/cplusplus
19.3.2 Security References
- OWASP Security Guidelines: https://owasp.org/
- DISA STIG Library: https://public.cyber.mil/stigs/
- GDPR Compliance: https://gdpr.eu/
- ISO 27001 Standard: https://www.iso.org/isoiec-27001-information-security.html
19.4 Version History
| Version | Date | Author | Changes |
|---|---|---|---|
| 2.0 | 2024-12-28 | Development Team | Comprehensive PRD creation |
| 1.0 | Previous | Initial Team | Initial concept document |
19.5 Approval & Sign-off
| Role | Name | Date | Signature |
|---|---|---|---|
| Product Owner | [Name] | [Date] | [Signature] |
| Technical Lead | [Name] | [Date] | [Signature] |
| Security Officer | [Name] | [Date] | [Signature] |
| Legal Counsel | [Name] | [Date] | [Signature] |
Document Control
Classification: Confidential
Distribution: Internal Use Only
Review Cycle: Quarterly
Next Review: Q2 2025
Document Owner: Product Management Team
Contact: product@hiddenroute.com
End of Document