1719 lines
53 KiB
Markdown
1719 lines
53 KiB
Markdown
# RFCP Phase 3.0: Complete Architecture Refactor
|
||
|
||
**Date:** February 1, 2025
|
||
**Type:** Major Refactor
|
||
**Version:** 3.0.0
|
||
**Author:** Claude + Oleg
|
||
|
||
---
|
||
|
||
## 📋 Executive Summary
|
||
|
||
This document describes a complete architectural refactor of RFCP (RF Coverage Planner) to address fundamental performance and maintainability issues that accumulated through iterative patching (Phases 2.0-2.5.1).
|
||
|
||
**Goals:**
|
||
1. Clean, modular architecture
|
||
2. 10x performance improvement for Detailed preset
|
||
3. Proper memory management (< 2GB peak)
|
||
4. Reliable app lifecycle (close actually works!)
|
||
5. UHF/VHF band support readiness
|
||
6. Maintainable, testable codebase
|
||
|
||
**Non-Goals:**
|
||
- Complete UI redesign (current UI is good)
|
||
- New features beyond UHF/VHF tab
|
||
- Cloud deployment (stays desktop-first)
|
||
|
||
---
|
||
|
||
## 🏗️ Current Architecture Problems
|
||
|
||
### Problem 1: Monolithic Coverage Service
|
||
```
|
||
coverage_service.py = 800+ lines
|
||
- Data loading
|
||
- Grid generation
|
||
- Point calculation
|
||
- Parallel orchestration
|
||
- Result aggregation
|
||
- ALL propagation models mixed together
|
||
```
|
||
|
||
**Impact:** Can't test individual components, can't swap models, hard to optimize.
|
||
|
||
### Problem 2: Memory Explosion
|
||
```
|
||
Main process: Load 350k buildings (500MB)
|
||
Worker 1: Copy 350k buildings (500MB)
|
||
Worker 2: Copy 350k buildings (500MB)
|
||
... × 6 workers
|
||
Total: 3-4 GB just for building data!
|
||
```
|
||
|
||
**Impact:** 8GB RAM usage, OOM on smaller machines.
|
||
|
||
### Problem 3: Nested Loop Hell
|
||
```python
|
||
for point in grid: # 868 points
|
||
for building in buildings: # 50 buildings
|
||
for wall in walls: # 300 walls
|
||
for polygon in obstacles: # 50 polygons
|
||
check_intersection() # 4 nested loops!
|
||
```
|
||
|
||
**Impact:** O(n⁴) complexity, 340ms/point.
|
||
|
||
### Problem 4: Electron-Python Lifecycle
|
||
```
|
||
Electron starts → spawns Python
|
||
User clicks X → Electron closes → Python orphaned
|
||
Multiple kill strategies → still doesn't work reliably
|
||
```
|
||
|
||
**Impact:** Zombie processes, user frustration.
|
||
|
||
### Problem 5: No Clear Separation of Concerns
|
||
```
|
||
Propagation physics mixed with:
|
||
- File I/O
|
||
- Caching logic
|
||
- Parallel processing
|
||
- HTTP API handling
|
||
- Progress reporting
|
||
```
|
||
|
||
**Impact:** Can't unit test propagation models.
|
||
|
||
---
|
||
|
||
## 🎯 New Architecture Overview
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ RFCP Desktop App │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||
│ │ Electron │ │ React │ │ WebSocket │ │
|
||
│ │ Shell │◄─┤ Frontend │◄─┤ Connection │ │
|
||
│ └──────┬──────┘ └─────────────┘ └───────────┬─────────────┘ │
|
||
│ │ │ │
|
||
│ │ spawn + lifecycle │ bidirectional │
|
||
│ ▼ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||
│ │ Python Backend ││
|
||
│ │ ┌───────────────────────────────────────────────────────┐ ││
|
||
│ │ │ FastAPI + WebSocket │ ││
|
||
│ │ └───────────────────────────────────────────────────────┘ ││
|
||
│ │ │ ││
|
||
│ │ ┌───────────────────────────┴───────────────────────────┐ ││
|
||
│ │ │ Coverage Engine │ ││
|
||
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ ││
|
||
│ │ │ │ GridService │ │CalcService │ │ ResultService │ │ ││
|
||
│ │ │ └─────────────┘ └──────┬──────┘ └─────────────────┘ │ ││
|
||
│ │ └─────────────────────────┼─────────────────────────────┘ ││
|
||
│ │ │ ││
|
||
│ │ ┌─────────────────────────┴─────────────────────────────┐ ││
|
||
│ │ │ Propagation Models │ ││
|
||
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ││
|
||
│ │ │ │ Okumura │ │ COST-231 │ │ ITU-R │ │ Longley │ │ ││
|
||
│ │ │ │ Hata │ │ │ │ P.1546 │ │ Rice │ │ ││
|
||
│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ││
|
||
│ │ └───────────────────────────────────────────────────────┘ ││
|
||
│ │ │ ││
|
||
│ │ ┌─────────────────────────┴─────────────────────────────┐ ││
|
||
│ │ │ Data Services │ ││
|
||
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ││
|
||
│ │ │ │ Terrain │ │ Building │ │ Spatial │ │ Cache │ │ ││
|
||
│ │ │ │ Service │ │ Service │ │ Index │ │ Service │ │ ││
|
||
│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ││
|
||
│ │ └───────────────────────────────────────────────────────┘ ││
|
||
│ └─────────────────────────────────────────────────────────────┘│
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 New Project Structure
|
||
|
||
```
|
||
rfcp/
|
||
├── backend/
|
||
│ ├── app/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── main.py # FastAPI app + WebSocket
|
||
│ │ ├── config.py # Configuration management
|
||
│ │ │
|
||
│ │ ├── api/
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── routes/
|
||
│ │ │ │ ├── coverage.py # REST endpoints
|
||
│ │ │ │ ├── terrain.py # Terrain/elevation API
|
||
│ │ │ │ ├── system.py # Health, info, shutdown
|
||
│ │ │ │ └── sites.py # Site management
|
||
│ │ │ └── websocket.py # WebSocket handlers
|
||
│ │ │
|
||
│ │ ├── core/ # Core business logic
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── engine.py # CoverageEngine orchestrator
|
||
│ │ │ ├── grid.py # Grid generation
|
||
│ │ │ ├── calculator.py # Point calculation coordinator
|
||
│ │ │ └── result.py # Result aggregation
|
||
│ │ │
|
||
│ │ ├── models/ # Propagation models
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── base.py # Abstract PropagationModel
|
||
│ │ │ ├── free_space.py # Free space path loss
|
||
│ │ │ ├── okumura_hata.py # Okumura-Hata (150-1500 MHz)
|
||
│ │ │ ├── cost231_hata.py # COST-231 Hata (1500-2000 MHz)
|
||
│ │ │ ├── cost231_wi.py # COST-231 Walfisch-Ikegami
|
||
│ │ │ ├── itu_r_p1546.py # ITU-R P.1546 (30-3000 MHz)
|
||
│ │ │ ├── itu_r_p526.py # Diffraction (knife-edge)
|
||
│ │ │ ├── longley_rice.py # Irregular Terrain Model
|
||
│ │ │ └── uhf_vhf.py # UHF/VHF specific models
|
||
│ │ │
|
||
│ │ ├── services/ # Data services
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── terrain.py # SRTM terrain data
|
||
│ │ │ ├── buildings.py # OSM buildings
|
||
│ │ │ ├── spatial_index.py # R-tree spatial queries
|
||
│ │ │ ├── cache.py # Unified cache management
|
||
│ │ │ └── osm_client.py # OSM API client
|
||
│ │ │
|
||
│ │ ├── parallel/ # Parallel processing
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── manager.py # Shared memory manager
|
||
│ │ │ ├── worker.py # Worker process logic
|
||
│ │ │ └── pool.py # Process pool with cleanup
|
||
│ │ │
|
||
│ │ ├── geometry/ # Geometry operations
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── haversine.py # Distance calculations
|
||
│ │ │ ├── los.py # Line of sight checks
|
||
│ │ │ ├── intersection.py # Line-polygon intersection
|
||
│ │ │ ├── diffraction.py # Knife-edge diffraction
|
||
│ │ │ └── reflection.py # Reflection calculations
|
||
│ │ │
|
||
│ │ └── utils/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── logging.py # Structured logging
|
||
│ │ ├── progress.py # Progress reporting
|
||
│ │ └── units.py # Unit conversions
|
||
│ │
|
||
│ ├── tests/ # Unit tests
|
||
│ │ ├── test_models/
|
||
│ │ ├── test_services/
|
||
│ │ ├── test_geometry/
|
||
│ │ └── test_integration/
|
||
│ │
|
||
│ └── requirements.txt
|
||
│
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── App.tsx
|
||
│ │ ├── components/
|
||
│ │ │ ├── map/
|
||
│ │ │ │ ├── Map.tsx
|
||
│ │ │ │ ├── CoverageLayer.tsx
|
||
│ │ │ │ ├── ElevationLayer.tsx
|
||
│ │ │ │ └── SiteMarker.tsx
|
||
│ │ │ ├── panels/
|
||
│ │ │ │ ├── SitePanel.tsx
|
||
│ │ │ │ ├── SettingsPanel.tsx
|
||
│ │ │ │ ├── LTE_Panel.tsx # LTE band settings
|
||
│ │ │ │ └── UHF_VHF_Panel.tsx # NEW: UHF/VHF settings
|
||
│ │ │ └── common/
|
||
│ │ │ ├── LoadingOverlay.tsx
|
||
│ │ │ └── ProgressBar.tsx
|
||
│ │ │
|
||
│ │ ├── hooks/
|
||
│ │ │ ├── useWebSocket.ts # WebSocket connection
|
||
│ │ │ ├── useCoverage.ts # Coverage state
|
||
│ │ │ └── useProgress.ts # Progress tracking
|
||
│ │ │
|
||
│ │ ├── services/
|
||
│ │ │ ├── api.ts # REST API client
|
||
│ │ │ └── websocket.ts # WebSocket client
|
||
│ │ │
|
||
│ │ └── store/
|
||
│ │ ├── sites.ts
|
||
│ │ ├── settings.ts
|
||
│ │ └── coverage.ts
|
||
│ │
|
||
│ └── package.json
|
||
│
|
||
├── desktop/
|
||
│ ├── main.js # Electron main process
|
||
│ ├── preload.js # Preload scripts
|
||
│ └── package.json
|
||
│
|
||
└── installer/
|
||
├── build.bat
|
||
├── rfcp-server.spec
|
||
└── scripts/
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Core Components Specification
|
||
|
||
### 1. CoverageEngine (Orchestrator)
|
||
|
||
```python
|
||
# backend/app/core/engine.py
|
||
|
||
from abc import ABC, abstractmethod
|
||
from dataclasses import dataclass
|
||
from typing import List, Optional, AsyncIterator
|
||
from enum import Enum
|
||
|
||
class BandType(Enum):
|
||
LTE = "lte" # 700-2600 MHz
|
||
UHF = "uhf" # 400-520 MHz
|
||
VHF = "vhf" # 136-174 MHz
|
||
CUSTOM = "custom" # User-defined
|
||
|
||
class PresetType(Enum):
|
||
FAST = "fast" # Terrain only
|
||
STANDARD = "standard" # + Buildings
|
||
DETAILED = "detailed" # + Reflections/Diffraction
|
||
|
||
@dataclass
|
||
class Site:
|
||
id: str
|
||
lat: float
|
||
lon: float
|
||
height: float # meters AGL
|
||
power: float # dBm
|
||
gain: float # dBi
|
||
frequency: float # MHz
|
||
band_type: BandType
|
||
azimuth: float = 0 # degrees
|
||
beamwidth: float = 360
|
||
tilt: float = 0 # electrical downtilt
|
||
|
||
@dataclass
|
||
class CoverageSettings:
|
||
radius: float # meters
|
||
resolution: float # meters
|
||
min_signal: float # dBm
|
||
preset: PresetType
|
||
band_type: BandType
|
||
|
||
# Model-specific
|
||
environment: str = "urban" # urban, suburban, rural, open
|
||
terrain_enabled: bool = True
|
||
buildings_enabled: bool = True
|
||
diffraction_enabled: bool = True
|
||
reflection_enabled: bool = False # OFF by default now!
|
||
|
||
@dataclass
|
||
class PointResult:
|
||
lat: float
|
||
lon: float
|
||
rsrp: float # dBm
|
||
distance: float # meters
|
||
path_loss: float # dB
|
||
terrain_loss: float # dB
|
||
building_loss: float # dB
|
||
diffraction_loss: float # dB
|
||
has_los: bool
|
||
model_used: str
|
||
|
||
@dataclass
|
||
class CoverageResult:
|
||
points: List[PointResult]
|
||
stats: dict
|
||
computation_time: float
|
||
models_used: List[str]
|
||
|
||
|
||
class CoverageEngine:
|
||
"""
|
||
Main orchestrator for coverage calculations.
|
||
|
||
Responsibilities:
|
||
- Coordinate data loading
|
||
- Select appropriate propagation model
|
||
- Manage parallel computation
|
||
- Aggregate results
|
||
|
||
Does NOT:
|
||
- Implement propagation physics (delegated to models)
|
||
- Handle HTTP/WebSocket (delegated to API layer)
|
||
- Manage caching (delegated to services)
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
terrain_service: TerrainService,
|
||
building_service: BuildingService,
|
||
cache_service: CacheService,
|
||
):
|
||
self.terrain = terrain_service
|
||
self.buildings = building_service
|
||
self.cache = cache_service
|
||
self._models = self._init_models()
|
||
|
||
def _init_models(self) -> dict:
|
||
"""Initialize available propagation models."""
|
||
return {
|
||
# LTE bands (700-2600 MHz)
|
||
(BandType.LTE, "urban"): Cost231HataModel(),
|
||
(BandType.LTE, "suburban"): OkumuraHataModel(),
|
||
(BandType.LTE, "rural"): OkumuraHataModel(),
|
||
|
||
# UHF (400-520 MHz)
|
||
(BandType.UHF, "urban"): OkumuraHataModel(),
|
||
(BandType.UHF, "rural"): LongleyRiceModel(),
|
||
|
||
# VHF (136-174 MHz)
|
||
(BandType.VHF, "urban"): ITUR_P1546Model(),
|
||
(BandType.VHF, "rural"): LongleyRiceModel(),
|
||
}
|
||
|
||
def select_model(self, band: BandType, environment: str) -> PropagationModel:
|
||
"""Select best propagation model for given band and environment."""
|
||
key = (band, environment)
|
||
if key in self._models:
|
||
return self._models[key]
|
||
# Fallback
|
||
return OkumuraHataModel()
|
||
|
||
async def calculate(
|
||
self,
|
||
sites: List[Site],
|
||
settings: CoverageSettings,
|
||
progress_callback: Optional[callable] = None
|
||
) -> CoverageResult:
|
||
"""
|
||
Main calculation entry point.
|
||
|
||
Steps:
|
||
1. Generate grid
|
||
2. Load terrain data
|
||
3. Load building data (if needed)
|
||
4. Select propagation model
|
||
5. Calculate points (parallel)
|
||
6. Aggregate results
|
||
"""
|
||
start_time = time.time()
|
||
|
||
# Step 1: Generate grid
|
||
grid = GridService.generate(
|
||
sites=sites,
|
||
radius=settings.radius,
|
||
resolution=settings.resolution
|
||
)
|
||
|
||
if progress_callback:
|
||
await progress_callback(phase="grid", progress=0.05)
|
||
|
||
# Step 2: Load terrain
|
||
bbox = grid.bounding_box
|
||
terrain_data = await self.terrain.load_region(bbox)
|
||
|
||
if progress_callback:
|
||
await progress_callback(phase="terrain", progress=0.15)
|
||
|
||
# Step 3: Load buildings (if needed)
|
||
building_data = None
|
||
if settings.buildings_enabled and settings.preset != PresetType.FAST:
|
||
building_data = await self.buildings.load_region(bbox)
|
||
|
||
if progress_callback:
|
||
await progress_callback(phase="buildings", progress=0.25)
|
||
|
||
# Step 4: Select model
|
||
model = self.select_model(settings.band_type, settings.environment)
|
||
|
||
# Step 5: Calculate (parallel)
|
||
calculator = PointCalculator(
|
||
model=model,
|
||
terrain=terrain_data,
|
||
buildings=building_data,
|
||
settings=settings
|
||
)
|
||
|
||
results = await calculator.calculate_parallel(
|
||
sites=sites,
|
||
points=grid.points,
|
||
progress_callback=progress_callback
|
||
)
|
||
|
||
# Step 6: Aggregate
|
||
return CoverageResult(
|
||
points=results,
|
||
stats=self._compute_stats(results),
|
||
computation_time=time.time() - start_time,
|
||
models_used=[model.name]
|
||
)
|
||
|
||
def _compute_stats(self, results: List[PointResult]) -> dict:
|
||
"""Compute coverage statistics."""
|
||
rsrp_values = [r.rsrp for r in results]
|
||
return {
|
||
"min_rsrp": min(rsrp_values),
|
||
"max_rsrp": max(rsrp_values),
|
||
"avg_rsrp": sum(rsrp_values) / len(rsrp_values),
|
||
"los_percentage": sum(1 for r in results if r.has_los) / len(results) * 100,
|
||
"total_points": len(results)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. Propagation Models (Clean Interface)
|
||
|
||
```python
|
||
# backend/app/models/base.py
|
||
|
||
from abc import ABC, abstractmethod
|
||
from dataclasses import dataclass
|
||
from typing import Optional
|
||
|
||
@dataclass
|
||
class PropagationInput:
|
||
"""Input for propagation calculation."""
|
||
frequency_mhz: float
|
||
distance_m: float
|
||
tx_height_m: float
|
||
rx_height_m: float
|
||
environment: str # urban, suburban, rural, open
|
||
|
||
# Optional terrain info
|
||
terrain_clearance_m: Optional[float] = None
|
||
terrain_roughness_m: Optional[float] = None
|
||
|
||
# Optional building info
|
||
building_height_m: Optional[float] = None
|
||
street_width_m: Optional[float] = None
|
||
building_separation_m: Optional[float] = None
|
||
|
||
@dataclass
|
||
class PropagationOutput:
|
||
"""Output from propagation calculation."""
|
||
path_loss_db: float
|
||
model_name: str
|
||
is_los: bool
|
||
breakdown: dict # Detailed loss components
|
||
|
||
|
||
class PropagationModel(ABC):
|
||
"""
|
||
Abstract base class for all propagation models.
|
||
|
||
Each model implements a single, well-defined propagation algorithm.
|
||
Models are stateless and can be called concurrently.
|
||
"""
|
||
|
||
@property
|
||
@abstractmethod
|
||
def name(self) -> str:
|
||
"""Model name for logging/display."""
|
||
pass
|
||
|
||
@property
|
||
@abstractmethod
|
||
def frequency_range(self) -> tuple:
|
||
"""Valid frequency range (min_mhz, max_mhz)."""
|
||
pass
|
||
|
||
@property
|
||
@abstractmethod
|
||
def distance_range(self) -> tuple:
|
||
"""Valid distance range (min_m, max_m)."""
|
||
pass
|
||
|
||
@abstractmethod
|
||
def calculate(self, input: PropagationInput) -> PropagationOutput:
|
||
"""
|
||
Calculate path loss for given input.
|
||
|
||
This method MUST be:
|
||
- Stateless (no side effects)
|
||
- Thread-safe (can be called concurrently)
|
||
- Fast (no I/O, no heavy computation)
|
||
"""
|
||
pass
|
||
|
||
def is_valid_for(self, input: PropagationInput) -> bool:
|
||
"""Check if this model is valid for given input."""
|
||
freq_min, freq_max = self.frequency_range
|
||
dist_min, dist_max = self.distance_range
|
||
|
||
return (
|
||
freq_min <= input.frequency_mhz <= freq_max and
|
||
dist_min <= input.distance_m <= dist_max
|
||
)
|
||
|
||
|
||
# backend/app/models/okumura_hata.py
|
||
|
||
class OkumuraHataModel(PropagationModel):
|
||
"""
|
||
Okumura-Hata empirical propagation model.
|
||
|
||
Valid for:
|
||
- Frequency: 150-1500 MHz
|
||
- Distance: 1-20 km
|
||
- TX height: 30-200 m
|
||
- RX height: 1-10 m
|
||
|
||
Reference: Hata (1980), "Empirical Formula for Propagation Loss
|
||
in Land Mobile Radio Services"
|
||
"""
|
||
|
||
@property
|
||
def name(self) -> str:
|
||
return "Okumura-Hata"
|
||
|
||
@property
|
||
def frequency_range(self) -> tuple:
|
||
return (150, 1500)
|
||
|
||
@property
|
||
def distance_range(self) -> tuple:
|
||
return (1000, 20000) # 1-20 km
|
||
|
||
def calculate(self, input: PropagationInput) -> PropagationOutput:
|
||
f = input.frequency_mhz
|
||
d = input.distance_m / 1000 # Convert to km
|
||
hb = input.tx_height_m
|
||
hm = input.rx_height_m
|
||
|
||
# Mobile antenna height correction factor
|
||
if input.environment == "urban" and f >= 400:
|
||
# Large city
|
||
a_hm = 3.2 * (math.log10(11.75 * hm) ** 2) - 4.97
|
||
else:
|
||
# Medium/small city
|
||
a_hm = (1.1 * math.log10(f) - 0.7) * hm - (1.56 * math.log10(f) - 0.8)
|
||
|
||
# Basic path loss (urban)
|
||
L_urban = (
|
||
69.55 +
|
||
26.16 * math.log10(f) -
|
||
13.82 * math.log10(hb) -
|
||
a_hm +
|
||
(44.9 - 6.55 * math.log10(hb)) * math.log10(d)
|
||
)
|
||
|
||
# Environment correction
|
||
if input.environment == "suburban":
|
||
L = L_urban - 2 * (math.log10(f / 28) ** 2) - 5.4
|
||
elif input.environment == "rural":
|
||
L = L_urban - 4.78 * (math.log10(f) ** 2) + 18.33 * math.log10(f) - 40.94
|
||
elif input.environment == "open":
|
||
L = L_urban - 4.78 * (math.log10(f) ** 2) + 18.33 * math.log10(f) - 35.94
|
||
else:
|
||
L = L_urban
|
||
|
||
return PropagationOutput(
|
||
path_loss_db=L,
|
||
model_name=self.name,
|
||
is_los=False, # Okumura-Hata is for NLOS
|
||
breakdown={
|
||
"basic_loss": L_urban,
|
||
"environment_correction": L - L_urban,
|
||
"antenna_correction": a_hm
|
||
}
|
||
)
|
||
|
||
|
||
# backend/app/models/free_space.py
|
||
|
||
class FreeSpaceModel(PropagationModel):
|
||
"""
|
||
Free Space Path Loss (FSPL) model.
|
||
|
||
Used as baseline and for LOS conditions.
|
||
|
||
FSPL = 20*log10(d) + 20*log10(f) + 32.45
|
||
where d in km, f in MHz
|
||
"""
|
||
|
||
@property
|
||
def name(self) -> str:
|
||
return "Free-Space"
|
||
|
||
@property
|
||
def frequency_range(self) -> tuple:
|
||
return (1, 100000) # Practically unlimited
|
||
|
||
@property
|
||
def distance_range(self) -> tuple:
|
||
return (1, 1000000) # 1m to 1000km
|
||
|
||
def calculate(self, input: PropagationInput) -> PropagationOutput:
|
||
d_km = input.distance_m / 1000
|
||
f = input.frequency_mhz
|
||
|
||
# Avoid log(0)
|
||
d_km = max(d_km, 0.001)
|
||
|
||
L = 20 * math.log10(d_km) + 20 * math.log10(f) + 32.45
|
||
|
||
return PropagationOutput(
|
||
path_loss_db=L,
|
||
model_name=self.name,
|
||
is_los=True,
|
||
breakdown={
|
||
"distance_loss": 20 * math.log10(d_km),
|
||
"frequency_loss": 20 * math.log10(f),
|
||
"constant": 32.45
|
||
}
|
||
)
|
||
|
||
|
||
# backend/app/models/cost231_hata.py
|
||
|
||
class Cost231HataModel(PropagationModel):
|
||
"""
|
||
COST-231 Hata model (extension of Okumura-Hata).
|
||
|
||
Valid for:
|
||
- Frequency: 1500-2000 MHz
|
||
- Distance: 1-20 km
|
||
|
||
Better for LTE bands than original Okumura-Hata.
|
||
"""
|
||
|
||
@property
|
||
def name(self) -> str:
|
||
return "COST-231-Hata"
|
||
|
||
@property
|
||
def frequency_range(self) -> tuple:
|
||
return (1500, 2000)
|
||
|
||
@property
|
||
def distance_range(self) -> tuple:
|
||
return (1000, 20000)
|
||
|
||
def calculate(self, input: PropagationInput) -> PropagationOutput:
|
||
f = input.frequency_mhz
|
||
d = input.distance_m / 1000
|
||
hb = input.tx_height_m
|
||
hm = input.rx_height_m
|
||
|
||
# Mobile antenna correction (medium city)
|
||
a_hm = (1.1 * math.log10(f) - 0.7) * hm - (1.56 * math.log10(f) - 0.8)
|
||
|
||
# Metropolitan center correction
|
||
C_m = 3 if input.environment == "urban" else 0
|
||
|
||
L = (
|
||
46.3 +
|
||
33.9 * math.log10(f) -
|
||
13.82 * math.log10(hb) -
|
||
a_hm +
|
||
(44.9 - 6.55 * math.log10(hb)) * math.log10(d) +
|
||
C_m
|
||
)
|
||
|
||
return PropagationOutput(
|
||
path_loss_db=L,
|
||
model_name=self.name,
|
||
is_los=False,
|
||
breakdown={
|
||
"base_loss": 46.3,
|
||
"frequency_term": 33.9 * math.log10(f),
|
||
"height_gain": -13.82 * math.log10(hb),
|
||
"mobile_correction": -a_hm,
|
||
"distance_term": (44.9 - 6.55 * math.log10(hb)) * math.log10(d),
|
||
"metro_correction": C_m
|
||
}
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
### 3. UHF/VHF Specific Models
|
||
|
||
```python
|
||
# backend/app/models/uhf_vhf.py
|
||
|
||
"""
|
||
UHF/VHF Propagation Models
|
||
|
||
UHF (Ultra High Frequency): 300-3000 MHz, typically 400-520 MHz for radio
|
||
VHF (Very High Frequency): 30-300 MHz, typically 136-174 MHz for radio
|
||
|
||
Key differences from LTE:
|
||
1. Lower frequency = better penetration, longer range
|
||
2. Terrain diffraction more important than building reflection
|
||
3. Tropospheric effects at longer ranges
|
||
4. Different antenna characteristics
|
||
"""
|
||
|
||
class ITUR_P1546Model(PropagationModel):
|
||
"""
|
||
ITU-R P.1546 model for point-to-area predictions.
|
||
|
||
Valid for:
|
||
- Frequency: 30-3000 MHz
|
||
- Distance: 1-1000 km
|
||
- Time percentages: 1%, 10%, 50%
|
||
|
||
Best for: VHF/UHF broadcasting and land mobile services.
|
||
|
||
Reference: ITU-R P.1546-6 (2019)
|
||
"""
|
||
|
||
@property
|
||
def name(self) -> str:
|
||
return "ITU-R-P.1546"
|
||
|
||
@property
|
||
def frequency_range(self) -> tuple:
|
||
return (30, 3000)
|
||
|
||
@property
|
||
def distance_range(self) -> tuple:
|
||
return (1000, 1000000) # 1-1000 km
|
||
|
||
def calculate(self, input: PropagationInput) -> PropagationOutput:
|
||
"""
|
||
Simplified P.1546 implementation.
|
||
Full implementation would include:
|
||
- Terrain clearance angle
|
||
- Mixed path (land/sea)
|
||
- Time variability
|
||
"""
|
||
f = input.frequency_mhz
|
||
d = input.distance_m / 1000 # km
|
||
h1 = input.tx_height_m
|
||
h2 = input.rx_height_m
|
||
|
||
# Nominal frequency bands
|
||
if f < 100:
|
||
f_nom = 100
|
||
elif f < 600:
|
||
f_nom = 600
|
||
else:
|
||
f_nom = 2000
|
||
|
||
# Basic field strength at 1 kW ERP (from curves)
|
||
# Simplified: using regression fit
|
||
E_ref = 106.9 - 20 * math.log10(d) # dBμV/m at 1kW
|
||
|
||
# Height gain for transmitter
|
||
if h1 > 10:
|
||
delta_h1 = 20 * math.log10(h1 / 10)
|
||
else:
|
||
delta_h1 = 0
|
||
|
||
# Frequency correction
|
||
delta_f = 20 * math.log10(f / f_nom)
|
||
|
||
# Convert field strength to path loss
|
||
# L = 139.3 - E + 20*log10(f) (for 50Ω)
|
||
E = E_ref + delta_h1 - delta_f
|
||
L = 139.3 - E + 20 * math.log10(f)
|
||
|
||
return PropagationOutput(
|
||
path_loss_db=L,
|
||
model_name=self.name,
|
||
is_los=d < 5, # Assume LOS for very short distances
|
||
breakdown={
|
||
"reference_field": E_ref,
|
||
"height_gain": delta_h1,
|
||
"frequency_correction": delta_f,
|
||
"path_loss": L
|
||
}
|
||
)
|
||
|
||
|
||
class LongleyRiceModel(PropagationModel):
|
||
"""
|
||
Longley-Rice Irregular Terrain Model (ITM).
|
||
|
||
Best for:
|
||
- VHF/UHF over irregular terrain
|
||
- Point-to-point links
|
||
- Distances 1-2000 km
|
||
|
||
Note: Full implementation requires terrain profile.
|
||
This is a simplified version.
|
||
|
||
Reference: NTIA Report 82-100
|
||
"""
|
||
|
||
@property
|
||
def name(self) -> str:
|
||
return "Longley-Rice"
|
||
|
||
@property
|
||
def frequency_range(self) -> tuple:
|
||
return (20, 20000) # 20 MHz to 20 GHz
|
||
|
||
@property
|
||
def distance_range(self) -> tuple:
|
||
return (1000, 2000000) # 1-2000 km
|
||
|
||
def calculate(self, input: PropagationInput) -> PropagationOutput:
|
||
"""
|
||
Simplified Longley-Rice (area mode).
|
||
|
||
For proper implementation, use:
|
||
- splat! (open source)
|
||
- NTIA ITM reference implementation
|
||
"""
|
||
f = input.frequency_mhz
|
||
d = input.distance_m / 1000
|
||
h1 = input.tx_height_m
|
||
h2 = input.rx_height_m
|
||
|
||
# Terrain irregularity parameter (simplified)
|
||
delta_h = input.terrain_roughness_m or 90 # Default: rolling hills
|
||
|
||
# Free space loss
|
||
L_fs = 32.45 + 20 * math.log10(d) + 20 * math.log10(f)
|
||
|
||
# Terrain clutter loss (simplified)
|
||
if delta_h < 10:
|
||
L_terrain = 0 # Flat
|
||
elif delta_h < 50:
|
||
L_terrain = 5 # Gently rolling
|
||
elif delta_h < 150:
|
||
L_terrain = 10 # Rolling hills
|
||
else:
|
||
L_terrain = 15 # Mountains
|
||
|
||
# Height gain
|
||
h_eff = h1 + h2
|
||
if h_eff > 20:
|
||
height_gain = 10 * math.log10(h_eff / 20)
|
||
else:
|
||
height_gain = 0
|
||
|
||
L = L_fs + L_terrain - height_gain
|
||
|
||
return PropagationOutput(
|
||
path_loss_db=L,
|
||
model_name=self.name,
|
||
is_los=delta_h < 10 and d < 10,
|
||
breakdown={
|
||
"free_space_loss": L_fs,
|
||
"terrain_loss": L_terrain,
|
||
"height_gain": height_gain
|
||
}
|
||
)
|
||
|
||
|
||
class KnifeEdgeDiffractionModel:
|
||
"""
|
||
Single knife-edge diffraction model.
|
||
|
||
Used for calculating loss when terrain blocks LOS.
|
||
|
||
Reference: ITU-R P.526
|
||
"""
|
||
|
||
@staticmethod
|
||
def calculate_loss(
|
||
d1_m: float, # Distance TX to obstacle
|
||
d2_m: float, # Distance obstacle to RX
|
||
h_m: float, # Obstacle height above LOS
|
||
wavelength_m: float
|
||
) -> float:
|
||
"""
|
||
Calculate diffraction loss over single knife edge.
|
||
|
||
Returns:
|
||
Loss in dB (always positive or zero)
|
||
"""
|
||
# Fresnel-Kirchhoff parameter
|
||
v = h_m * math.sqrt(2 * (d1_m + d2_m) / (wavelength_m * d1_m * d2_m))
|
||
|
||
# Diffraction loss (Lee approximation)
|
||
if v < -0.78:
|
||
# Well below LOS
|
||
L = 0
|
||
elif v < 0:
|
||
# Below LOS
|
||
L = 6.02 + 9.11 * v - 1.27 * v**2
|
||
elif v < 2.4:
|
||
# Above LOS
|
||
L = 6.02 + 9.11 * v + 1.65 * v**2
|
||
else:
|
||
# Deep shadow
|
||
L = 12.95 + 20 * math.log10(v)
|
||
|
||
return max(0, L)
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Shared Memory Architecture
|
||
|
||
```python
|
||
# backend/app/parallel/manager.py
|
||
|
||
"""
|
||
Shared Memory Manager for parallel processing.
|
||
|
||
Key insight: Instead of copying 350k buildings to each worker,
|
||
we store data in shared memory that all workers can READ.
|
||
|
||
Memory layout:
|
||
┌─────────────────────────────────────────────┐
|
||
│ Shared Memory Block │
|
||
├─────────────────────────────────────────────┤
|
||
│ Terrain Data (SRTM tiles) │
|
||
│ - Heights as flat array │
|
||
│ - Tile metadata (bounds, resolution) │
|
||
├─────────────────────────────────────────────┤
|
||
│ Building Data │
|
||
│ - Centroids (lat, lon) as arrays │
|
||
│ - Heights as array │
|
||
│ - Polygon vertices (flattened) │
|
||
│ - Polygon offsets (to reconstruct) │
|
||
├─────────────────────────────────────────────┤
|
||
│ Spatial Index │
|
||
│ - Grid cell assignments │
|
||
│ - Building IDs per cell │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
```python
|
||
import multiprocessing.shared_memory as shm
|
||
import numpy as np
|
||
from dataclasses import dataclass
|
||
from typing import Optional
|
||
import struct
|
||
|
||
@dataclass
|
||
class SharedTerrainData:
|
||
"""Terrain data in shared memory."""
|
||
shm_name: str
|
||
shape: tuple # (rows, cols)
|
||
bounds: tuple # (min_lat, min_lon, max_lat, max_lon)
|
||
resolution: float # arc-seconds
|
||
|
||
def get_array(self) -> np.ndarray:
|
||
"""Attach to shared memory and return numpy array."""
|
||
existing_shm = shm.SharedMemory(name=self.shm_name)
|
||
return np.ndarray(self.shape, dtype=np.int16, buffer=existing_shm.buf)
|
||
|
||
@dataclass
|
||
class SharedBuildingData:
|
||
"""Building data in shared memory."""
|
||
shm_centroids_name: str # (N, 2) float64 - lat, lon
|
||
shm_heights_name: str # (N,) float32 - heights
|
||
shm_vertices_name: str # (total_verts, 2) float64 - all vertices
|
||
shm_offsets_name: str # (N+1,) int32 - where each polygon starts
|
||
count: int
|
||
|
||
def get_centroids(self) -> np.ndarray:
|
||
existing = shm.SharedMemory(name=self.shm_centroids_name)
|
||
return np.ndarray((self.count, 2), dtype=np.float64, buffer=existing.buf)
|
||
|
||
def get_polygon(self, idx: int) -> np.ndarray:
|
||
"""Get polygon vertices for building idx."""
|
||
offsets = self._get_offsets()
|
||
vertices = self._get_vertices()
|
||
start, end = offsets[idx], offsets[idx + 1]
|
||
return vertices[start:end]
|
||
|
||
|
||
class SharedMemoryManager:
|
||
"""
|
||
Manages shared memory blocks for parallel processing.
|
||
|
||
Usage:
|
||
# In main process
|
||
manager = SharedMemoryManager()
|
||
terrain_ref = manager.store_terrain(terrain_data)
|
||
buildings_ref = manager.store_buildings(buildings)
|
||
|
||
# Pass references to workers
|
||
pool.map(worker_func, points, terrain_ref, buildings_ref)
|
||
|
||
# Workers attach to shared memory
|
||
terrain = terrain_ref.get_array() # No copy!
|
||
|
||
# Cleanup
|
||
manager.cleanup()
|
||
"""
|
||
|
||
def __init__(self):
|
||
self._shm_blocks: list = []
|
||
|
||
def store_terrain(self, heights: np.ndarray, bounds: tuple, resolution: float) -> SharedTerrainData:
|
||
"""Store terrain heights in shared memory."""
|
||
# Create shared memory block
|
||
shm_block = shm.SharedMemory(create=True, size=heights.nbytes)
|
||
self._shm_blocks.append(shm_block)
|
||
|
||
# Copy data to shared memory
|
||
shm_array = np.ndarray(heights.shape, dtype=heights.dtype, buffer=shm_block.buf)
|
||
shm_array[:] = heights[:]
|
||
|
||
return SharedTerrainData(
|
||
shm_name=shm_block.name,
|
||
shape=heights.shape,
|
||
bounds=bounds,
|
||
resolution=resolution
|
||
)
|
||
|
||
def store_buildings(self, buildings: list) -> SharedBuildingData:
|
||
"""Store building data in shared memory."""
|
||
n = len(buildings)
|
||
|
||
# Extract centroids
|
||
centroids = np.array([
|
||
[b['centroid_lat'], b['centroid_lon']]
|
||
for b in buildings
|
||
], dtype=np.float64)
|
||
|
||
# Extract heights
|
||
heights = np.array([
|
||
b.get('height', 10.0) for b in buildings
|
||
], dtype=np.float32)
|
||
|
||
# Flatten all polygon vertices
|
||
all_vertices = []
|
||
offsets = [0]
|
||
|
||
for b in buildings:
|
||
coords = b.get('geometry', {}).get('coordinates', [[]])[0]
|
||
for lon, lat in coords:
|
||
all_vertices.append([lat, lon])
|
||
offsets.append(len(all_vertices))
|
||
|
||
vertices = np.array(all_vertices, dtype=np.float64)
|
||
offsets = np.array(offsets, dtype=np.int32)
|
||
|
||
# Create shared memory blocks
|
||
shm_centroids = shm.SharedMemory(create=True, size=centroids.nbytes)
|
||
shm_heights = shm.SharedMemory(create=True, size=heights.nbytes)
|
||
shm_vertices = shm.SharedMemory(create=True, size=vertices.nbytes)
|
||
shm_offsets = shm.SharedMemory(create=True, size=offsets.nbytes)
|
||
|
||
self._shm_blocks.extend([shm_centroids, shm_heights, shm_vertices, shm_offsets])
|
||
|
||
# Copy data
|
||
np.ndarray(centroids.shape, dtype=centroids.dtype, buffer=shm_centroids.buf)[:] = centroids
|
||
np.ndarray(heights.shape, dtype=heights.dtype, buffer=shm_heights.buf)[:] = heights
|
||
np.ndarray(vertices.shape, dtype=vertices.dtype, buffer=shm_vertices.buf)[:] = vertices
|
||
np.ndarray(offsets.shape, dtype=offsets.dtype, buffer=shm_offsets.buf)[:] = offsets
|
||
|
||
return SharedBuildingData(
|
||
shm_centroids_name=shm_centroids.name,
|
||
shm_heights_name=shm_heights.name,
|
||
shm_vertices_name=shm_vertices.name,
|
||
shm_offsets_name=shm_offsets.name,
|
||
count=n
|
||
)
|
||
|
||
def cleanup(self):
|
||
"""Release all shared memory blocks."""
|
||
for block in self._shm_blocks:
|
||
try:
|
||
block.close()
|
||
block.unlink()
|
||
except Exception:
|
||
pass
|
||
self._shm_blocks.clear()
|
||
```
|
||
|
||
---
|
||
|
||
### 5. WebSocket Communication
|
||
|
||
```python
|
||
# backend/app/api/websocket.py
|
||
|
||
from fastapi import WebSocket, WebSocketDisconnect
|
||
from typing import Dict, Set
|
||
import asyncio
|
||
import json
|
||
|
||
class ConnectionManager:
|
||
"""Manage WebSocket connections."""
|
||
|
||
def __init__(self):
|
||
self.active_connections: Set[WebSocket] = set()
|
||
self._calculation_tasks: Dict[str, asyncio.Task] = {}
|
||
|
||
async def connect(self, websocket: WebSocket):
|
||
await websocket.accept()
|
||
self.active_connections.add(websocket)
|
||
|
||
def disconnect(self, websocket: WebSocket):
|
||
self.active_connections.discard(websocket)
|
||
|
||
async def broadcast(self, message: dict):
|
||
"""Send message to all connected clients."""
|
||
for connection in self.active_connections:
|
||
try:
|
||
await connection.send_json(message)
|
||
except Exception:
|
||
pass
|
||
|
||
async def send_progress(self, calc_id: str, phase: str, progress: float, eta: float = None):
|
||
"""Send calculation progress update."""
|
||
await self.broadcast({
|
||
"type": "progress",
|
||
"calculation_id": calc_id,
|
||
"phase": phase,
|
||
"progress": progress,
|
||
"eta_seconds": eta
|
||
})
|
||
|
||
async def send_result(self, calc_id: str, result: dict):
|
||
"""Send calculation result."""
|
||
await self.broadcast({
|
||
"type": "result",
|
||
"calculation_id": calc_id,
|
||
"data": result
|
||
})
|
||
|
||
async def send_error(self, calc_id: str, error: str):
|
||
"""Send error message."""
|
||
await self.broadcast({
|
||
"type": "error",
|
||
"calculation_id": calc_id,
|
||
"message": error
|
||
})
|
||
|
||
|
||
manager = ConnectionManager()
|
||
|
||
|
||
@app.websocket("/ws")
|
||
async def websocket_endpoint(websocket: WebSocket):
|
||
await manager.connect(websocket)
|
||
|
||
try:
|
||
while True:
|
||
data = await websocket.receive_json()
|
||
|
||
if data["type"] == "calculate":
|
||
# Start calculation
|
||
calc_id = data.get("id", str(uuid.uuid4()))
|
||
|
||
async def progress_callback(phase: str, progress: float, eta: float = None):
|
||
await manager.send_progress(calc_id, phase, progress, eta)
|
||
|
||
try:
|
||
result = await engine.calculate(
|
||
sites=data["sites"],
|
||
settings=CoverageSettings(**data["settings"]),
|
||
progress_callback=progress_callback
|
||
)
|
||
await manager.send_result(calc_id, result.to_dict())
|
||
|
||
except Exception as e:
|
||
await manager.send_error(calc_id, str(e))
|
||
|
||
elif data["type"] == "cancel":
|
||
# Cancel calculation
|
||
calc_id = data.get("id")
|
||
if calc_id in manager._calculation_tasks:
|
||
manager._calculation_tasks[calc_id].cancel()
|
||
|
||
elif data["type"] == "ping":
|
||
await websocket.send_json({"type": "pong"})
|
||
|
||
except WebSocketDisconnect:
|
||
manager.disconnect(websocket)
|
||
```
|
||
|
||
```typescript
|
||
// frontend/src/hooks/useWebSocket.ts
|
||
|
||
import { useEffect, useRef, useState, useCallback } from 'react';
|
||
|
||
interface ProgressUpdate {
|
||
type: 'progress';
|
||
calculation_id: string;
|
||
phase: string;
|
||
progress: number;
|
||
eta_seconds?: number;
|
||
}
|
||
|
||
interface ResultUpdate {
|
||
type: 'result';
|
||
calculation_id: string;
|
||
data: CoverageResult;
|
||
}
|
||
|
||
interface ErrorUpdate {
|
||
type: 'error';
|
||
calculation_id: string;
|
||
message: string;
|
||
}
|
||
|
||
type WSMessage = ProgressUpdate | ResultUpdate | ErrorUpdate;
|
||
|
||
export function useWebSocket() {
|
||
const ws = useRef<WebSocket | null>(null);
|
||
const [connected, setConnected] = useState(false);
|
||
const [progress, setProgress] = useState<ProgressUpdate | null>(null);
|
||
|
||
const callbacks = useRef<{
|
||
onResult?: (result: CoverageResult) => void;
|
||
onError?: (error: string) => void;
|
||
}>({});
|
||
|
||
useEffect(() => {
|
||
const connect = () => {
|
||
ws.current = new WebSocket('ws://127.0.0.1:8888/ws');
|
||
|
||
ws.current.onopen = () => {
|
||
setConnected(true);
|
||
console.log('[WS] Connected');
|
||
};
|
||
|
||
ws.current.onclose = () => {
|
||
setConnected(false);
|
||
console.log('[WS] Disconnected, reconnecting...');
|
||
setTimeout(connect, 2000);
|
||
};
|
||
|
||
ws.current.onmessage = (event) => {
|
||
const msg: WSMessage = JSON.parse(event.data);
|
||
|
||
switch (msg.type) {
|
||
case 'progress':
|
||
setProgress(msg);
|
||
break;
|
||
case 'result':
|
||
callbacks.current.onResult?.(msg.data);
|
||
setProgress(null);
|
||
break;
|
||
case 'error':
|
||
callbacks.current.onError?.(msg.message);
|
||
setProgress(null);
|
||
break;
|
||
}
|
||
};
|
||
};
|
||
|
||
connect();
|
||
|
||
return () => {
|
||
ws.current?.close();
|
||
};
|
||
}, []);
|
||
|
||
const calculate = useCallback((
|
||
sites: Site[],
|
||
settings: CoverageSettings,
|
||
onResult: (result: CoverageResult) => void,
|
||
onError: (error: string) => void
|
||
) => {
|
||
if (!ws.current || ws.current.readyState !== WebSocket.OPEN) {
|
||
onError('WebSocket not connected');
|
||
return;
|
||
}
|
||
|
||
const calcId = crypto.randomUUID();
|
||
callbacks.current = { onResult, onError };
|
||
|
||
ws.current.send(JSON.stringify({
|
||
type: 'calculate',
|
||
id: calcId,
|
||
sites,
|
||
settings
|
||
}));
|
||
|
||
return calcId;
|
||
}, []);
|
||
|
||
const cancel = useCallback((calcId: string) => {
|
||
ws.current?.send(JSON.stringify({
|
||
type: 'cancel',
|
||
id: calcId
|
||
}));
|
||
}, []);
|
||
|
||
return { connected, progress, calculate, cancel };
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. Clean Electron Lifecycle
|
||
|
||
```javascript
|
||
// desktop/main.js
|
||
|
||
const { app, BrowserWindow } = require('electron');
|
||
const { spawn } = require('child_process');
|
||
const path = require('path');
|
||
const http = require('http');
|
||
|
||
let mainWindow = null;
|
||
let backendProcess = null;
|
||
let isQuitting = false;
|
||
|
||
// Configuration
|
||
const CONFIG = {
|
||
backendHost: '127.0.0.1',
|
||
backendPort: 8888,
|
||
healthCheckInterval: 1000,
|
||
shutdownTimeout: 5000,
|
||
};
|
||
|
||
// ==================== Backend Management ====================
|
||
|
||
function getBackendPath() {
|
||
if (app.isPackaged) {
|
||
return path.join(process.resourcesPath, 'rfcp-server.exe');
|
||
}
|
||
return path.join(__dirname, '..', 'installer', 'dist', 'rfcp-server.exe');
|
||
}
|
||
|
||
async function startBackend() {
|
||
const exePath = getBackendPath();
|
||
|
||
console.log('[Backend] Starting:', exePath);
|
||
|
||
backendProcess = spawn(exePath, [], {
|
||
stdio: ['ignore', 'pipe', 'pipe'],
|
||
env: {
|
||
...process.env,
|
||
RFCP_HOST: CONFIG.backendHost,
|
||
RFCP_PORT: String(CONFIG.backendPort),
|
||
},
|
||
windowsHide: true,
|
||
});
|
||
|
||
backendProcess.stdout.on('data', (data) => {
|
||
console.log('[Backend]', data.toString().trim());
|
||
});
|
||
|
||
backendProcess.stderr.on('data', (data) => {
|
||
console.error('[Backend Error]', data.toString().trim());
|
||
});
|
||
|
||
backendProcess.on('exit', (code) => {
|
||
console.log('[Backend] Exited with code:', code);
|
||
backendProcess = null;
|
||
|
||
if (!isQuitting) {
|
||
console.log('[Backend] Unexpected exit, restarting...');
|
||
setTimeout(startBackend, 1000);
|
||
}
|
||
});
|
||
|
||
// Wait for backend to be ready
|
||
await waitForBackend();
|
||
}
|
||
|
||
async function waitForBackend(maxAttempts = 30) {
|
||
for (let i = 0; i < maxAttempts; i++) {
|
||
try {
|
||
await checkHealth();
|
||
console.log('[Backend] Ready!');
|
||
return;
|
||
} catch {
|
||
await sleep(500);
|
||
}
|
||
}
|
||
throw new Error('Backend failed to start');
|
||
}
|
||
|
||
function checkHealth() {
|
||
return new Promise((resolve, reject) => {
|
||
const req = http.request({
|
||
hostname: CONFIG.backendHost,
|
||
port: CONFIG.backendPort,
|
||
path: '/api/health',
|
||
method: 'GET',
|
||
timeout: 1000,
|
||
}, (res) => {
|
||
if (res.statusCode === 200) resolve();
|
||
else reject(new Error(`Health check failed: ${res.statusCode}`));
|
||
});
|
||
|
||
req.on('error', reject);
|
||
req.on('timeout', () => reject(new Error('Timeout')));
|
||
req.end();
|
||
});
|
||
}
|
||
|
||
async function stopBackend() {
|
||
if (!backendProcess) return;
|
||
|
||
console.log('[Backend] Stopping...');
|
||
|
||
// Step 1: Request graceful shutdown
|
||
try {
|
||
await fetch(`http://${CONFIG.backendHost}:${CONFIG.backendPort}/api/system/shutdown`, {
|
||
method: 'POST',
|
||
signal: AbortSignal.timeout(2000),
|
||
});
|
||
console.log('[Backend] Shutdown requested');
|
||
} catch {
|
||
console.log('[Backend] Shutdown request failed, force killing');
|
||
}
|
||
|
||
// Step 2: Wait for process to exit
|
||
const exitPromise = new Promise((resolve) => {
|
||
if (!backendProcess) {
|
||
resolve();
|
||
return;
|
||
}
|
||
|
||
backendProcess.once('exit', resolve);
|
||
setTimeout(resolve, CONFIG.shutdownTimeout);
|
||
});
|
||
|
||
// Step 3: Force kill if still running
|
||
if (backendProcess) {
|
||
backendProcess.kill('SIGTERM');
|
||
await exitPromise;
|
||
|
||
if (backendProcess) {
|
||
backendProcess.kill('SIGKILL');
|
||
}
|
||
}
|
||
|
||
console.log('[Backend] Stopped');
|
||
}
|
||
|
||
// ==================== Window Management ====================
|
||
|
||
function createWindow() {
|
||
mainWindow = new BrowserWindow({
|
||
width: 1400,
|
||
height: 900,
|
||
webPreferences: {
|
||
nodeIntegration: false,
|
||
contextIsolation: true,
|
||
preload: path.join(__dirname, 'preload.js'),
|
||
},
|
||
icon: path.join(__dirname, 'icon.png'),
|
||
title: 'RFCP - RF Coverage Planner',
|
||
});
|
||
|
||
// Load frontend
|
||
if (process.env.NODE_ENV === 'development') {
|
||
mainWindow.loadURL('http://localhost:5173');
|
||
mainWindow.webContents.openDevTools();
|
||
} else {
|
||
mainWindow.loadFile(path.join(__dirname, '..', 'frontend', 'dist', 'index.html'));
|
||
}
|
||
|
||
// Handle close
|
||
mainWindow.on('close', async (event) => {
|
||
if (!isQuitting) {
|
||
event.preventDefault();
|
||
await quit();
|
||
}
|
||
});
|
||
|
||
mainWindow.on('closed', () => {
|
||
mainWindow = null;
|
||
});
|
||
}
|
||
|
||
// ==================== App Lifecycle ====================
|
||
|
||
async function quit() {
|
||
if (isQuitting) return;
|
||
isQuitting = true;
|
||
|
||
console.log('[App] Quitting...');
|
||
|
||
await stopBackend();
|
||
|
||
if (mainWindow) {
|
||
mainWindow.destroy();
|
||
}
|
||
|
||
app.quit();
|
||
}
|
||
|
||
// App ready
|
||
app.whenReady().then(async () => {
|
||
try {
|
||
await startBackend();
|
||
createWindow();
|
||
} catch (error) {
|
||
console.error('[App] Failed to start:', error);
|
||
app.quit();
|
||
}
|
||
});
|
||
|
||
// All windows closed
|
||
app.on('window-all-closed', () => {
|
||
quit();
|
||
});
|
||
|
||
// Before quit
|
||
app.on('before-quit', (event) => {
|
||
if (!isQuitting) {
|
||
event.preventDefault();
|
||
quit();
|
||
}
|
||
});
|
||
|
||
// macOS activate
|
||
app.on('activate', () => {
|
||
if (BrowserWindow.getAllWindows().length === 0) {
|
||
createWindow();
|
||
}
|
||
});
|
||
|
||
// Signals
|
||
process.on('SIGINT', quit);
|
||
process.on('SIGTERM', quit);
|
||
|
||
// ==================== Utilities ====================
|
||
|
||
function sleep(ms) {
|
||
return new Promise(resolve => setTimeout(resolve, ms));
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Performance Targets
|
||
|
||
| Metric | Current | Target | Improvement |
|
||
|--------|---------|--------|-------------|
|
||
| Fast preset (2km) | 0.03s | 0.03s | Same |
|
||
| Standard preset (5km) | 38s | 20s | 2x |
|
||
| Detailed preset (5km) | 300s (timeout) | 45s | 6x |
|
||
| Memory peak | 8 GB | 1.5 GB | 5x |
|
||
| App close | Broken | Works | ∞ |
|
||
| UHF/VHF support | No | Yes | New |
|
||
|
||
---
|
||
|
||
## 🗓️ Implementation Phases
|
||
|
||
### Phase 3.1: Core Infrastructure (Week 1)
|
||
- [ ] New project structure
|
||
- [ ] PropagationModel interface + FreeSpace, OkumuraHata
|
||
- [ ] TerrainService (port existing SRTM code)
|
||
- [ ] Basic CoverageEngine (single-threaded)
|
||
- [ ] Unit tests for models
|
||
|
||
### Phase 3.2: Data Services (Week 2)
|
||
- [ ] BuildingService (port existing OSM code)
|
||
- [ ] SpatialIndex service
|
||
- [ ] CacheService (unified caching)
|
||
- [ ] SharedMemoryManager
|
||
- [ ] Integration tests
|
||
|
||
### Phase 3.3: Parallel Processing (Week 3)
|
||
- [ ] PointCalculator with shared memory
|
||
- [ ] Worker pool with clean lifecycle
|
||
- [ ] Progress reporting
|
||
- [ ] Cancellation support
|
||
- [ ] Performance benchmarks
|
||
|
||
### Phase 3.4: API + Frontend (Week 4)
|
||
- [ ] WebSocket API
|
||
- [ ] useWebSocket hook
|
||
- [ ] Progress UI
|
||
- [ ] UHF/VHF tab
|
||
- [ ] Electron cleanup
|
||
|
||
### Phase 3.5: Polish + Testing (Week 5)
|
||
- [ ] End-to-end tests
|
||
- [ ] Documentation
|
||
- [ ] PyInstaller build
|
||
- [ ] Performance validation
|
||
- [ ] Release
|
||
|
||
---
|
||
|
||
## 🧪 Testing Strategy
|
||
|
||
```
|
||
tests/
|
||
├── unit/
|
||
│ ├── test_models/
|
||
│ │ ├── test_free_space.py
|
||
│ │ ├── test_okumura_hata.py
|
||
│ │ └── test_cost231.py
|
||
│ ├── test_geometry/
|
||
│ │ ├── test_haversine.py
|
||
│ │ └── test_intersection.py
|
||
│ └── test_services/
|
||
│ ├── test_terrain.py
|
||
│ └── test_buildings.py
|
||
│
|
||
├── integration/
|
||
│ ├── test_engine.py
|
||
│ ├── test_parallel.py
|
||
│ └── test_websocket.py
|
||
│
|
||
└── e2e/
|
||
├── test_coverage_calculation.py
|
||
└── test_app_lifecycle.py
|
||
```
|
||
|
||
**Test coverage targets:**
|
||
- Models: 100% (pure functions, easy to test)
|
||
- Services: 90%
|
||
- Engine: 85%
|
||
- API: 80%
|
||
|
||
---
|
||
|
||
## 📝 Migration Guide
|
||
|
||
### What to Keep (copy directly):
|
||
1. SRTM terrain loading logic
|
||
2. OSM building parsing
|
||
3. R-tree spatial index
|
||
4. Frontend React components
|
||
5. Elevation layer visualization
|
||
|
||
### What to Rewrite:
|
||
1. coverage_service.py → core/engine.py + core/calculator.py
|
||
2. dominant_path_service.py → models/ + geometry/
|
||
3. parallel_coverage_service.py → parallel/
|
||
4. main.js → Clean lifecycle management
|
||
|
||
### Data Compatibility:
|
||
- Existing terrain cache: Compatible ✅
|
||
- Existing OSM cache: Compatible ✅
|
||
- Site JSON format: Compatible ✅
|
||
- Coverage result format: Compatible ✅
|
||
|
||
---
|
||
|
||
## 🎯 Success Criteria
|
||
|
||
1. **Performance:**
|
||
- Detailed preset completes in < 60 seconds
|
||
- Memory usage < 2 GB peak
|
||
|
||
2. **Reliability:**
|
||
- App close works first time, every time
|
||
- No zombie processes
|
||
- Clean error handling
|
||
|
||
3. **Maintainability:**
|
||
- Each model in separate file
|
||
- Unit tests for all models
|
||
- Clear separation of concerns
|
||
|
||
4. **Features:**
|
||
- UHF/VHF tab functional
|
||
- Multiple propagation models selectable
|
||
- Progress visible via WebSocket
|
||
|
||
---
|
||
|
||
## 🚀 Ready to Start?
|
||
|
||
This architecture document is the blueprint.
|
||
|
||
**Next step:** Give Claude Code Phase 3.1 tasks to create:
|
||
1. New project structure
|
||
2. Base propagation model interface
|
||
3. FreeSpace and OkumuraHata models
|
||
4. Basic engine skeleton
|
||
|
||
Shall I create the Phase 3.1 task file?
|