dragndrop_hld/README.md

# Verofy HLD Auto Upload & QC Tool - Phase 1

A web-based tool for uploading and validating Verofy HLD shapefiles with comprehensive Quality Control checks.

## Features

- Drag & drop ZIP file upload interface
- Comprehensive QC validation for 10 required shapefiles
- WGS 84 projection verification
- Attribute field validation with detailed error reporting
- VerofyMapID collection on successful QC

## Architecture

- **Frontend**: JavaScript web application with drag & drop interface
- **Backend**: FastAPI Python server with shapefile validation
- **Port**: 8000 (backend), open index.html directly for frontend

## Installation

### Prerequisites
- Python 3.10+
- uv package manager (or pip)

### Backend Setup

```bash
cd backend

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
~/.local/bin/uv venv
~/.local/bin/uv pip install -r requirements.txt
```

## Running the Application

### Start Backend Server

```bash
cd backend
source .venv/bin/activate
python main.py
```

The server will start on `http://localhost:8000`

### Open Frontend

Open `frontend/index.html` in your web browser. The frontend will automatically connect to the backend at `http://localhost:8000`.

## Usage

1. Open `frontend/index.html` in your browser
2. Drag and drop a ZIP file containing shapefiles (or click to browse)
3. The system will:
   - Extract the ZIP file
   - Run comprehensive QC validation
   - If QC **fails**: Download a detailed error report (QC_report.txt)
   - If QC **passes**: Show a success message and prompt for VerofyMapID

## QC Validation Rules

The tool validates the following for each shapefile upload:

### Required Shapefiles (all 10 must be present)
- poles
- network_elements
- splicing
- sites
- parcels
- permits
- cabinet_boundaries
- segments
- access_points
- cables

### General Validation
1. **Projection**: All shapefiles must be in WGS 84 projection
2. **UID Field**: All shapefiles must have a UID field with unique integer values

### Shapefile-Specific Attribute Validation

#### Segments
- Type: Must be one of [Aerial, 3rd Party Duct, Underground, Existing VERO, Drop Cable]
- Group_01: Must be "Zone XX" format (XX = 2 digits)
- Conduit: Required for Underground type, format "(3|1)-1.25\" SDR 13.5 HDPE"

#### Access Points
- Type: Must be [Handhole, Cabinet]
- Group_01: Must be "Zone XX" format
- Latitude: Must be a number
- Longitude: Must be a number

#### Cabinet Boundaries
- Name: Must be "Zone XX Boundary" format

#### Permits
- Name: Must start with "ROW", "ROE", or "LLP"

#### Cables
- Name: Must begin with "XXXF." format (XXX = 3 digits)

#### Parcels
- Name: Must be exactly "Parcel"
- Group_01: Must be "Zone XX" format

#### Sites
- Type: Must be one of [School, Hub Site, MDU, Administration, MTU, Dwelling Unit, Vendor Location, Cell Tower, Government, Data Center, Hosptial, Internet, Large Business, Library, Museum, Power Substation, Small Business, Small Cell, Stadium, University, Splice Point, ILA, SFR, Vacant Lot, Mobile Home, Meet Me]
- Address: Must be populated
- State: Must be 2 letters
- Zip: Must be 5 digits
- BEN#: Must be an integer
- Latitude: Must be a number
- Longitude: Must be a number

#### Splicing
- AKA: Must begin with "YYY_Y" format (Y = letters)
- Type: Must be [MST, Splice, FTP]
- Group_01: Must be "Zone XX" format
- Latitude: Must be a number
- Longitude: Must be a number

#### Network Elements
- Type: Must be [Slack Coil, Anchor, Bore Pit, Riser]
- Group_01: Must be "Zone XX" format
- Latitude: Must be a number
- Longitude: Must be a number

#### Poles
- Pole_Tag: Must be populated
- Pole_Owner: Must be populated
- Group_01: Must be "Zone XX" format
- Latitude: Must be a number
- Longitude: Must be a number

## Error Reporting

When QC fails:
- A `QC_report.txt` file is automatically downloaded
- The report lists all validation errors
- If more than 10 features fail the same validation, it shows "10 or more features failed XXX"
- If a shapefile fails multiple QC issues, each is listed separately

## Project Structure

```
dragnddrop/
├── backend/
│   ├── .venv/              # Virtual environment
│   ├── main.py             # FastAPI server
│   ├── qc_validator.py     # QC validation logic
│   ├── requirements.txt    # Python dependencies
│   └── server.log          # Server logs
├── frontend/
│   ├── index.html          # Main UI
│   ├── upload.js           # Upload logic
│   └── style.css           # Styling
├── temp/                   # Temporary upload directory
├── samplefiles/            # Sample shapefiles for reference
└── README.md               # This file
```

## Phase 1 Notes

- Phase 1 focuses on QC validation only
- VerofyMapID is collected but not yet sent to any API (planned for Phase 2)
- The `verofy_api/` and `oldqc/` folders are for Phase 2 and not used in Phase 1

## Development

### Dependencies
- **fastapi**: Web framework
- **uvicorn**: ASGI server
- **python-multipart**: File upload support
- **pyshp**: Shapefile reading library

### Testing

Test with the sample upload file:
```bash
curl -X POST -F "file=@sampleupload.zip" http://localhost:8000/upload
```

## Troubleshooting

- **CORS errors**: Make sure the backend is running on port 8000
- **File not found errors**: Ensure ZIP contains shapefiles in root or one subdirectory
- **Validation errors**: Check QC_report.txt for detailed error messages