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

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

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:

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