📍 Proximity Alert App

1. Getting Started
2. First-Time Setup & Authentication
3. Main Interface Overview
4. Settings Panel Guide
5. Project Details, Voice Notes & Photos
6. Core Features
7. Advanced Features
8. AI Intel Research NEW
9. Market Intelligence NEW
10. Live Field Activity Dashboard NEW
11. Troubleshooting
12. Quick Reference
13. Privacy & Security

1. Open Safari (iPhone) or Chrome (Android)
2. Navigate to: myproximity.org
3. iPhone: Tap the Share button → "Add to Home Screen"
4. Android: Tap menu (⋮) → "Add to Home Screen"
5. Confirm installation and wait for icon to appear on home screen

1. Open the app from your home screen (NOT from Safari)
2. You'll see: "You need to authenticate to access this app" message displayed outside the white container on the blue background
3. Tap "Authenticate" button (also on blue background)
4. Enter your authorized work email when prompted
5. Check your email for the authentication code
6. Enter the code to complete authentication
7. Grant location permissions when requested

• Temporarily disable WiFi and use cellular data only
• Clear Safari cache: Settings → Safari → Clear History and Website Data
• Delete the app from home screen and reinstall
• Ensure cellular data is enabled for Safari in Settings
• Try again using cellular data connection only

Three icon-based buttons in a single row:

1. 🚀 Blitz: Plan optimized routes to multiple nearby sites
2. ➕ Add: Submit new project locations to the database
3. ⚙️ Settings: Access comprehensive settings panel REDESIGNED

1. Tap the ⚙️ button in the button row
2. Panel slides in from the right side of screen
3. Dimmed overlay appears behind panel
4. Tap X or overlay to close settings

• Large dropdown box at top
• Options: 10 miles, 5 miles, 2 miles, 1 mile
• Select your primary alert radius

• Circular button showing scale (e.g., "0.5×")
• Tap to cycle: 0.1× → 0.2× → 0.3× → ... → 1.0×
• Fine-tune your alert distance
• Consistent size across all devices FIXED

• Shows final alert distance in gradient box
• Example: "2.5 miles (5 × 0.5)"
• Updates instantly when you change settings
• Consistent formatting on mobile and desktop FIXED

1. Tap any location card from the main list
2. Modal window opens with full project information
3. Scroll to view all available details
4. Tap X or outside to close modal

1. Open project details by tapping a location card
2. Scroll to bottom to find the Voice Note section
3. Tap the red microphone button to start recording
4. Speak your message (up to 30 seconds)
5. Recording stops automatically at 30 seconds, or tap button again to stop early
6. Audio uploads automatically to cloud storage
7. Timestamp added to track when recording was made

• Audio player appears automatically if recording exists
• Shows timestamp: When recording was made
• Tap play button: Listen to audio note
• Progress bar: Shows playback position
• Time display: Current position / Total duration
• All organizers can hear voice notes left by others

Two ways to add photos:

1. Open project details by tapping a location card
2. Scroll to Site Photo section (below Voice Notes)
3. Tap "📷 Take Photo" button (blue button with camera icon)
4. Grant camera permission if prompted
5. Take your photo using device camera
6. Photo uploads automatically to cloud storage
7. Timestamp recorded: Date and time of photo saved
8. Thumbnail displays: Photo preview shown in details modal

1. Open project details by tapping a location card
2. Scroll to Site Photo section (below Voice Notes)
3. Tap "📤 Upload Photo" button (blue button next to Take Photo)
4. Select photo from your device's photo library
5. Photo uploads automatically to cloud storage
6. Perfect for: Previously captured photos, screenshots, or images from other sources

• Photo preview: Thumbnail displays automatically when photo exists
• View full-size: Tap green "View" button to see full resolution
• Timestamp shown: See when photo was uploaded
• Delete photo: Tap red "Delete" button to remove
• Replace photo: Tap "Take Photo" again to upload new one
• All organizers can view: Photos shared across team

1. Verify settings: Check alert distance and update interval
2. Tap "Start Tracking": Large blue button
3. Grant permissions: Allow location access if prompted
4. Wait for GPS lock: Usually 10-30 seconds
5. Green success message: "Location tracking started"

You'll receive an alert when:

• You enter alert radius of any project
• Notifications are enabled in settings
• App is actively tracking your location
• You haven't been alerted to this project yet in current session

1. Tap database selector: Shows current city/region
2. Choose different region: List of available databases appears
3. New data loads: Projects from selected region display
4. Selection persists: App remembers your choice

1. Tap 🚀 Blitz button in button row
2. Review nearby sites: List shows projects within range
3. See route details: Number of stops, total coverage
4. Tap "Open in Maps": Route opens in Google Maps
5. Follow navigation: Turn-by-turn directions to all sites

1. Locate search box: Above project list
2. Type contractor name: Partial matches work (e.g., "Electric")
3. Results update live: List filters as you type
4. View count: Shows "X projects found"
5. Clear filter: Tap "Clear Filter" button or delete text

1. Tap ➕ Add button in button row
2. Choose method:
   • Use Current Location: Adds GPS coordinates automatically
   • Enter Address: Type address, app finds coordinates
3. Fill in project details:
   • Contractor name (required)
   • Address (required if not using GPS)
   • City and State (required)
   • Work description (optional)
   • Additional details (optional)
4. Tap "Submit": Project adds to database
5. Confirmation: Success message displays
6. Appears immediately: New project shows in your list

1. Open project details: Tap any location card
2. Review project info: Confirm correct site
3. Tap "Mark as Visited": Green button in project details
4. Project hides for 24 hours: Won't show in "Closest 5" list
5. Visit logged: Your name and timestamp saved to database
6. Still searchable: Can find via contractor filter if needed
7. Auto-reappears: Returns to list after 24 hours

1. Open project details: Tap any location card
2. Scroll to bottom: Find red "Delete Project" button
3. Tap button: Confirmation prompt appears
4. Confirm deletion: Project permanently removed
5. Gone for everyone: All organizers lose access

How it works:

1. Step 1: Create a bounding box around your current position
   • Simple rectangular area defined by min/max latitude and longitude
   • Calculated using basic addition/subtraction (extremely fast)
   • No complex trigonometry or distance formulas needed
2. Step 2: Quick filter using simple comparisons
   • For each project: Is latitude between min and max?
   • For each project: Is longitude between min and max?
   • These are simple greater-than/less-than operations (microseconds each)
3. Step 3: Calculate distances only for nearby projects
   • Haversine formula only runs on projects inside bounding box
   • Typically reduces from 3,098 projects to ~1,240 projects
   • 60% reduction in expensive calculations!

Code implementation from location-manager.js:

// BOUNDING BOX OPTIMIZATION
// 1 degree latitude ≈ 69 miles, so ±0.725 degrees ≈ ±50 miles
const RADIUS_DEGREES = 0.725;
const latMin = currentLatitude - RADIUS_DEGREES;
const latMax = currentLatitude + RADIUS_DEGREES;
const lngMin = currentLongitude - RADIUS_DEGREES;
const lngMax = currentLongitude + RADIUS_DEGREES;

// Quick filter: only locations within bounding box
const nearbyLocations = allLocations.filter(location =>
    location.latitude >= latMin &&
    location.latitude <= latMax &&
    location.longitude >= lngMin &&
    location.longitude <= lngMax
);

// Calculate exact distances only on nearby subset
const locationsWithDistances = nearbyLocations.map(location => ({
    ...location,  // Preserves all fields including lastVisited and photoUrl
    distance: calculateDistance(currentLat, currentLng, location.latitude, location.longitude)
}));

Automatic recalculation triggers:

• Movement threshold: Every 0.5 miles you travel
• Database refresh: When you manually reload project data
• Start tracking: When you begin a new tracking session
• Smart updating: Only recalculates when necessary

Technical implementation:

const locationsWithDistances = nearbyLocations.map(location => ({
    ...location,  // Spread operator: preserves ALL fields
    distance: calculateDistance(...)
}));

Why this matters:

• Preserves lastVisited field: Visit tracking continues to work after recalculation
• Preserves photoUrl field: Site photos persist through bounding box updates
• Preserves all metadata: Voice notes, timestamps, visit history intact
• No data loss: Filtering operation only removes distant projects, never data fields

1. Open Safari/Chrome developer tools (Advanced settings required)
2. Start tracking and watch the console
3. Look for messages like: "📦 Bounding box: filtered 3098 → 1240 locations"
4. Drive 0.5+ miles and watch it recalculate
5. See real-time performance: Observe millisecond processing times

1. Open a project record from the Nearby Locations list
2. Click "View AI Research" button at the bottom of the details modal
3. Review/Edit Address in the popup before research starts
4. Add Optional Hint for additional context (e.g., "This is a Cambria Hotel project")
5. Click "Start Research" to begin AI analysis
6. Wait 10-15 seconds for comprehensive intelligence gathering

• Joseph → searches both "Joseph" and "Joe"
• Michael → searches both "Michael" and "Mike"
• William → searches "William," "Bill," and "Will"
• 40+ name mappings for comprehensive contractor discovery

• State and county electrical contractor license databases
• License holder registrations with owner names
• Business registrations tied to individual contractors

1. Click 👍 Accurate if the report information is correct
2. Click 👎 Inaccurate if something is wrong
3. Enter correction in the textarea (e.g., "Business at this address is Snarf's Sandwiches, not Gateway Studios")
4. Submit correction to save your feedback

Project says "Mike Smith Electric" but you've never heard of them.

1. Run AI Intel research
2. Discover they're a 15-year-old company with IBEW history
3. Find owner's name: Michael Smith (searched as both "Michael" and "Mike")
4. Locate their office and recent projects

AI incorrectly identifies a suite number.

1. Click 👎 Inaccurate
2. Enter: "Suite 200 is Snarf's Sandwiches, not Gateway Studios"
3. Submit correction
4. Future research in that city learns from your correction

1. Automatically appears below the main container when projects are loaded
2. Toggle views using the segmented control (PERMIT COUNT / DOLLAR VALUE)
3. Read percentages to understand market share
4. View totals for each union category

• 🟢 Green: IBEW union contractors
• 🟡 Yellow: UBCJA union contractors
• 🔴 Red: Non-union contractors

1. Tap the "📡 Live Feed" button at the top of the main screen
2. Opens in a new window showing all recent field activity
3. Auto-updates as new activities are posted
4. Can be open alongside your main Proximity App window

Combined cards show:

• Contractor name at the top
• 📍 Visited section with location and "Locate" button
• 🎤 Voice Note section with play button and transcription
• 📸 Photo displayed inline
• Timestamp showing when the visit occurred
• Organizer name who performed the activity

Use the filter buttons at the top of the feed:

• All Activity: Shows everything (visits, photos, voice notes, online/offline status)
• Voice Notes: Only shows activities with voice recordings
• Visits: Only shows marked visits and combined visit cards
• Photos: Only shows activities with photos

1. Find an activity card with a 🎤 Voice Note section
2. Tap the Play button to hear the audio
3. Use the progress bar to skip forward/backward
4. Read the transcription below the player
5. Tap Pause to stop playback

Note: Transcriptions are generated automatically using AI and may contain minor errors.

From the Active Organizers sidebar:

1. Find the organizer in the right sidebar
2. Tap their "Locate" button
3. Opens map showing their current or last known location

From a Visit card:

1. Find a visit or combined visit card
2. Tap the "Locate" button in the visited section
3. Opens map showing exact visit location

Scenario 1: Coordinating field staff

• Office manager opens Live Feed on laptop
• Sees 4 organizers active in different areas
• Notices voice note about a new project opening
• Sends another organizer to investigate based on the tip

Scenario 2: Verifying contractor presence

• Organizer marks "ABC Electric" as visited
• Takes a photo of their truck on site
• Records voice note: "3 trucks, crew of 8, working on east wing"
• All three activities combine into one card within 5 minutes
• Office has complete documentation of the visit

Scenario 3: Real-time situational awareness

• Multiple organizers working same neighborhood
• Live Feed shows all activity from the area
• Team can see what's already been documented
• Avoid duplicate visits, coordinate coverage

• First-time authentication intentionally displays on blue background
• Authentication elements fall outside the main container by design
• Complete the authentication process - don't close the app
• Once authenticated, normal interface appears properly

1. Temporarily disable WiFi - use cellular data only
2. Close app completely and reopen from home screen
3. Clear Safari cache: Settings → Safari → Clear History
4. Delete app from home screen and reinstall
5. Ensure you're using authorized work email
6. Contact union tech support to verify email authorization

• Authentication lasts 24 hours
• Daily re-authentication protects union data
• Process takes 30-60 seconds each morning
• Build it into your daily startup routine

• Check location permissions: Settings → App → Location
• Ensure "While Using" or "Always" is selected
• Move to area with clear sky view (away from buildings)
• Stop tracking, wait 10 seconds, restart tracking
• Close app completely and reopen
• Restart your phone if issue persists

• Urban canyons: Tall buildings block GPS - wait for clear area
• Weather: Heavy clouds affect accuracy - be patient
• Indoor use: GPS doesn't work indoors - go outside
• Vehicle interference: Some vehicles block signal - hold phone near window
• Cold start: First GPS lock takes longer - wait 60 seconds

1. Verify tracking is active (button shows "Stop Tracking")
2. Check notifications enabled in Settings panel
3. Ensure app has notification permissions in device settings
4. Verify you're within alert distance of a project
5. Confirm you haven't been alerted to this project already
6. Check device isn't in Do Not Disturb mode

• Reduce alert distance in Settings panel
• Use scale multiplier to fine-tune (e.g., 2 miles × 0.5 = 1 mile)
• Turn off notifications in Settings if you just want to browse
• Use contractor filter to focus on specific targets

• Grant microphone permission: Settings → App → Microphone
• Check Safari has microphone access on iOS
• Ensure you're authenticated properly
• Try closing and reopening project details
• Check device isn't in silent/DND mode blocking mic

• Check device volume and mute switch
• Ensure internet connection for audio file download
• Try refreshing the project details (close and reopen)
• Wait a few seconds for audio file to load
• Check Safari settings allow media playback

• Grant camera permission: Settings → App → Camera
• Check Safari has camera access on iOS
• Ensure you're authenticated properly
• Try closing and reopening project details
• Restart the app completely
• Check device camera works in other apps

• Check internet connection - uploads require network
• Wait a few seconds for upload to complete
• Try taking photo again if upload failed
• Ensure you have available storage on device
• Check if cellular data is enabled for Safari
• Try switching between WiFi and cellular

• Photos are compressed to save storage and speed up uploads
• Ensure good lighting when taking photos
• Hold phone steady and focus before capturing
• Clean camera lens before taking photo
• Quality sufficient for site documentation purposes

• Ensure you have latest version (check version in footer)
• Delete app from home screen and reinstall
• Clear Safari cache before reinstalling
• Elements should now be consistently sized across devices

• Settings auto-save - no save button needed
• Changes apply immediately to active tracking
• Try stopping and restarting tracking to force refresh
• Check that you closed settings panel (changes apply on close)

• Check internet connection - data requires network
• Tap "Refresh Data" button to reload
• Verify you're authenticated (check for auth prompt)
• Try switching to cellular data if on WiFi
• Contact union to confirm database has projects

• Projects hide from "Closest 5" list but remain searchable
• Use contractor filter to find visited sites if needed
• Projects reappear automatically after 24 hours
• Check "Last Visited" timestamp to see when marked

• Add zip code: Most common fix - "123 Main St, 63017"
• Include full address: Street, city, state, and zip
• Double-check city name: Ensure it matches the coordinates
• Use Google Maps: Verify address exists before submitting
• Warning is helpful: It caught a potential error - fix before submitting

• Ensure you have 2025 version with pagination fix
• Pagination state survives reload on iPhone PWA
• Use "Reset to Closest" to return to default view
• Clear filter if pagination seems stuck

• Use longer update intervals (1-2 minutes instead of 15-30 seconds)
• Stop tracking during breaks and when in office
• Keep phone plugged into vehicle charger during field work
• Close other background apps
• Enable Low Power Mode in device settings
• Reduce screen brightness

• Close app completely and reopen
• Restart your phone
• Clear Safari cache: Settings → Safari → Clear History
• Ensure device has available storage (need 500MB free)
• Delete and reinstall app from home screen

1. ☑️ Open app from home screen (never Safari)
2. ☑️ Complete authentication if prompted (24-hour expiry)
3. ☑️ Verify correct city database selected
4. ☑️ Open Settings (⚙️) and configure:
   • Alert distance for your territory
   • Update interval (30 sec recommended)
   • Notifications ON
5. ☑️ Tap "Start Tracking"
6. ☑️ Wait for GPS lock (~30 seconds)
7. ☑️ Mount phone securely in vehicle
8. ☑️ Connect to vehicle charger
9. ☑️ Begin organizing work!

1. ☑️ Add any new projects discovered during the day
2. ☑️ Upload site photos for documentation (if not done already)
3. ☑️ Record voice notes on visited sites (if not done already)
4. ☑️ Verify all visits marked (check for any missed "Mark as Visited")
5. ☑️ Delete only truly completed projects (signed/lost/duplicate)
6. ☑️ Review tomorrow's unvisited locations
7. ☑️ Stop tracking to save battery
8. ☑️ Plan tomorrow's route if needed