# KMZ Coverage System - Real Network Maps ✅

**Date:** February 11, 2026  
**Status:** ACTIVE

---

## Overview

The AFINET portal now uses **real KMZ coverage maps** for feasibility checks instead of simulated fibre nodes. This provides accurate coverage information based on actual network infrastructure.

---

## What Changed

### Before (Simulated):
- 42 simulated fibre nodes in database
- Distance calculations to nearest node
- Approximate coverage areas
- Manual node placement

### After (Real KMZ Maps):
- Real network coverage polygons from KMZ files
- Accurate zone detection (Harare, Bulawayo, etc.)
- Precise coverage boundaries
- Actual network infrastructure data

---

## KMZ Coverage System

### How It Works:

```
User enters address
    ↓
Geocode to coordinates
    ↓
Check KMZ coverage maps
    ↓
Determine coverage zone
    ↓
Calculate feasibility status
    ↓
Return result with zone info
```

### Coverage Files:

Location: `storage/app/coverage/`

Files:
- `harare.kmz` - Harare coverage map
- `bulawayo.kmz` - Bulawayo coverage map
- Additional zones as needed

### Service: `KmzCoverageService`

**Key Methods:**
- `checkCoverage($lat, $lon)` - Check if coordinates are in coverage
- `getAvailableZones()` - List all coverage zones
- `getCoveragePolygons($zone)` - Get polygons for a zone
- `clearCache()` - Clear cached coverage data

**Features:**
- Parses KMZ files (ZIP archives containing KML)
- Extracts polygon coordinates
- Point-in-polygon detection
- 24-hour caching for performance
- Multi-zone support

---

## Feasibility Information in Quotations

### Updated Format:

```
=== FEASIBILITY INFORMATION ===
Status: MEDIUM
Address: 456 Industrial Road, Bulawayo, Zimbabwe
Coordinates: -20.1500, 28.5833
Coverage Zone: Bulawayo Industrial

⚠️ EXTENSION REQUIRED
Extension Cost: $4700.00
IMPORTANT: Extension fee must be added to quotation

Coverage determined using real network KMZ maps
```

### Key Changes:

✅ **Coverage Zone** - Shows which KMZ zone (Harare, Bulawayo, etc.)  
✅ **Real Maps Note** - Indicates coverage from actual network maps  
✅ **Extension Info** - Clearly highlighted when required  
❌ **Node Distance** - Only shown if available (legacy data)  
❌ **Nearest Node** - Only shown if available (legacy data)  

---

## Database Changes

### FibreNode Table:

**Status:** CLEARED (0 nodes)

The `fibre_nodes` table is now empty as the system uses KMZ maps instead. The table structure remains for backward compatibility but is not actively used.

### FibreNodeSeeder:

**Status:** DEPRECATED

The seeder now skips node creation and shows a message:
```
⚠️  FibreNode seeding skipped - System uses KMZ coverage maps
📍 Coverage maps location: storage/app/coverage/*.kmz
```

---

## Coverage Zones

### Currently Supported:

1. **Harare** - Capital city, dense coverage
2. **Bulawayo** - Second city, good coverage

### Adding New Zones:

1. Obtain KMZ file from network team
2. Place in `storage/app/coverage/[zone-name].kmz`
3. System automatically detects new zone
4. No code changes required

---

## Feasibility Levels

### High Feasibility:
- Location is **inside** coverage polygon
- Direct connection available
- No extension required
- Packages available for immediate order

### Medium Feasibility:
- Location is **near** coverage polygon (within threshold)
- Extension may be required
- Extension cost calculated
- Quotation required for final pricing

### Low Feasibility:
- Location is **outside** all coverage zones
- Fibre not available
- Alternative solutions offered (Starlink, V-SAT)
- No fibre packages shown

---

## Technical Details

### KMZ File Format:

```
zone-name.kmz (ZIP archive)
  └── doc.kml (or zone-name.kml)
      └── Contains:
          - Placemarks
          - Polygons
          - Coordinates
          - Coverage boundaries
```

### Polygon Detection:

Uses ray-casting algorithm for point-in-polygon detection:
1. Cast ray from point to infinity
2. Count polygon edge intersections
3. Odd count = inside, Even count = outside

### Caching:

- Coverage polygons cached for 24 hours
- Cache key: `kmz_coverage_{zone}`
- Improves performance (ms vs seconds)
- Auto-refresh after TTL

---

## API Response Example

```json
{
  "feasibility_status": "medium",
  "coverage_zone": "harare",
  "in_coverage": false,
  "distance_to_coverage": 1.2,
  "extension_cost": 2400.00,
  "message": "Location is near coverage area. Extension required."
}
```

---

## Benefits of KMZ System

✅ **Accuracy** - Real network infrastructure data  
✅ **Precision** - Exact coverage boundaries  
✅ **Scalability** - Easy to add new zones  
✅ **Maintainability** - Update maps without code changes  
✅ **Performance** - Cached polygon data  
✅ **Flexibility** - Supports multiple coverage zones  
✅ **Reliability** - Based on actual network maps  

---

## Migration Notes

### From Simulated Nodes to KMZ:

**Completed:**
- ✅ FibreNode table cleared
- ✅ Seeder deprecated
- ✅ Quotation notes updated
- ✅ Coverage zone prioritized in output
- ✅ Node distance marked as legacy

**Backward Compatibility:**
- Node distance/name still shown if present (legacy data)
- Existing feasibility checks with node data still work
- No breaking changes to API

---

## Testing

### Verify KMZ Coverage:

```bash
cd info
php test-kmz-coverage.php
```

**Expected Output:**
- Available zones listed
- Test locations checked
- Coverage status determined
- Polygon count shown

### Debug KMZ Parsing:

```bash
cd info
php debug-kmz-parsing.php
```

**Expected Output:**
- KMZ files found
- File sizes shown
- ZIP archive opened
- KML content extracted

---

## Maintenance

### Updating Coverage Maps:

1. **Obtain New KMZ:**
   - Get updated KMZ from network team
   - Verify file format (KMZ with KML inside)

2. **Replace File:**
   ```bash
   cp new-harare.kmz storage/app/coverage/harare.kmz
   ```

3. **Clear Cache:**
   ```bash
   php artisan cache:clear
   # Or via code:
   # $kmzService->clearCache();
   ```

4. **Test:**
   ```bash
   php info/test-kmz-coverage.php
   ```

### Adding New Zone:

1. **Add KMZ File:**
   ```bash
   cp new-zone.kmz storage/app/coverage/mutare.kmz
   ```

2. **System Auto-Detects:**
   - No code changes needed
   - Zone name from filename
   - Automatically available

3. **Verify:**
   ```bash
   php artisan tinker
   >>> $service = new App\Services\KmzCoverageService();
   >>> $service->getAvailableZones();
   ```

---

## Troubleshooting

### KMZ Not Found:
```
Check: storage/app/coverage/[zone].kmz exists
Permissions: Ensure file is readable
Path: Verify storage path is correct
```

### No Polygons Extracted:
```
Check: KMZ contains valid KML file
Format: Verify KML has Placemark/Polygon elements
Test: Use debug-kmz-parsing.php to inspect
```

### Coverage Check Fails:
```
Check: Coordinates are valid (lat/lon)
Zone: Verify zone name matches KMZ filename
Cache: Try clearing cache
```

---

## Future Enhancements

1. **Visual Coverage Map** - Display KMZ polygons on frontend map
2. **Multi-Polygon Support** - Handle complex coverage areas
3. **Coverage Heatmap** - Show signal strength zones
4. **Auto-Update** - Sync KMZ files from network management system
5. **Coverage Analytics** - Track coverage check patterns
6. **Zone Priorities** - Prefer certain zones for overlapping areas

---

## Conclusion

The system now uses real KMZ coverage maps from actual network infrastructure, providing accurate feasibility checks. Simulated fibre nodes have been removed, and the system is fully operational with the KMZ-based approach.

**Key Points:**
- ✅ Real network maps (not simulated)
- ✅ Accurate coverage boundaries
- ✅ Easy to maintain and update
- ✅ Scalable to new zones
- ✅ Backward compatible