Josh Bruce Online

School Route Mapper - Comprehensive Documentation

Table of Contents

  1. System Overview
  2. Architecture & Components
  3. Data Model & Schema
  4. User Interface & Features
  5. API Reference
  6. Configuration & Settings
  7. Development & Deployment
  8. Technical Specifications

System Overview

Purpose

The School Route Mapper is a sophisticated web-based application designed for creating detailed interactive campus maps with advanced routing capabilities. It enables users to:

Key Features

Technology Stack

Architecture & Components

Core Architecture

The application follows a modular, event-driven architecture with clear separation of concerns:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   app.js        │    │  data-model.js  │    │  storage.js     │
│   (Controller)  │◄──►│   (Model)       │◄──►│   (Storage)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  ui-controls.js │    │ canvas-grid.js  │    │ drawing-tools.js│
│     (View)      │    │    (Canvas)     │    │    (Tools)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    poi.js       │    │   spline.js     │    │pathfinding-     │
│    (POIs)       │    │   (Curves)      │    │worker.js (AI)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Component Details

1. app.js - Main Application Controller

2. data-model.js - Core Data Management

3. canvas-grid.js - Rendering Engine

4. drawing-tools.js - Interactive Drawing System

5. poi.js - Point of Interest Management

6. pathfinding-worker.js - Route Calculation

7. storage.js - Data Persistence

8. ui-controls.js - User Interface Management

9. spline.js - Curve Generation

Data Model & Schema

Project Structure (.schoolmap.json)

{
  "schemaVersion": 1,
  "meta": {
    "title": "School Name",
    "created": "2024-01-01T00:00:00.000Z",
    "updated": "2024-01-01T00:00:00.000Z",
    "unit": "m",
    "grid": {
      "spacing": 0.5,
      "origin": [0, 0]
    },
    "render": {
      "theme": "light"
    }
  },
  "background": {
    "source": null,
    "transform": {
      "x": 0,
      "y": 0,
      "scale": 1,
      "rotation": 0
    },
    "opacity": 0.35
  },
  "categories": [...],
  "features": {
    "polylines": [...],
    "pois": [...]
  }
}

Category System

Categories define the visual appearance and routing behavior of map features:

{
  "id": "ext-wall",
  "name": "External Wall",
  "color": "#1f2937",
  "dash": [],
  "walkability": "blocked",
  "buffer": 0.5
}

Default Categories

  1. External Wall - Building perimeter (blocked)
  2. Internal Wall - Room divisions (blocked)
  3. Corridor Boundary - Hallway edges (blocked)
  4. Door - Entrances and exits (gate)
  5. Stairs - Vertical circulation (slow)
  6. Elevator - Accessible vertical circulation (slow)
  7. Ramp - Accessible paths (normal)
  8. Outdoor Path - Campus walkways (fast)
  9. Zebra Crossing - Safe road crossings (fast)
  10. Road - Vehicle areas to avoid (discouraged)
  11. Grass - Natural areas (slower)
  12. No-Go Area - Restricted zones (blocked)
  13. Shortcut - Quick routes (fast)

Walkability Types

Polyline Features

Represent linear features like walls, paths, and boundaries:

{
  "id": "pl-abc123",
  "category": "ext-wall",
  "points": [[0, 0], [10, 0], [10, 5]],
  "properties": {
    "level": 0,
    "description": "Main entrance wall"
  }
}

POI Features

Represent specific locations and facilities:

{
  "id": "poi-xyz789",
  "name": "Main Office",
  "type": "office",
  "pos": [5, 2.5],
  "properties": {
    "level": 0,
    "tags": ["admin", "reception"],
    "description": "School administration office"
  }
}

POI Types

User Interface & Features

Interface Layout

Top Navigation Bar

Left Toolbar - Edit Mode

Left Toolbar - Navigate Mode

Main Canvas

Right Panel

Keyboard Shortcuts

Features in Detail

Map Creation Workflow

  1. Setup: Configure grid spacing and load background image if available
  2. Structure Drawing: Use polyline tool to trace building outlines and walls
  3. Category Assignment: Apply appropriate categories for routing behavior
  4. POI Placement: Add locations like rooms, entrances, and facilities
  5. Validation: Test routes and verify navigation accuracy
  6. Export: Save project for sharing or deployment

Route Planning Process

  1. Mode Switch: Change to Navigate Mode
  2. Point Selection: Choose start and end locations from POI dropdown
  3. Checkpoints: Optionally add intermediate stops
  4. Calculation: Click “Calculate Route” to find optimal path
  5. Visualization: View route with distance and time estimates
  6. Animation: Watch step-by-step navigation simulation

API Reference

Main Application (app.js)

SchoolRouteMapperApp Class

class SchoolRouteMapperApp {
  constructor()                    // Initialize application
  initialize()                    // Setup all subsystems
  newProject(title)              // Create new project
  loadProject(project)           // Load existing project
  saveProject()                  // Save to localStorage
  exportProject(filename)        // Export to file
  loadDemo()                     // Load sample project
  getContentBounds()             // Calculate feature bounds
  render()                       // Refresh display
  destroy()                      // Cleanup resources
}

Data Model (data-model.js)

Core Functions

createEmptyProject(title)        // Create new project structure
validateProject(data)            // Validate project data
migrateProject(data)             // Upgrade old versions
createPolyline(categoryId, points, properties)
createPOI(name, type, position, properties)
generateId(prefix)               // Generate unique IDs
calculateBounds(features)        // Compute bounding box
findFeaturesNear(features, point, tolerance)
snapToGrid(point, spacing, origin)

CategoryManager Class

class CategoryManager {
  getCategory(id)                // Find category by ID
  addCategory(category)          // Add new category
  updateCategory(id, updates)    // Modify category
  removeCategory(id)             // Delete category
  getAllCategories()             // List all categories
  getWalkableCategories()        // Filter passable types
  getBlockedCategories()         // Filter blocked types
}

Drawing Tools (drawing-tools.js)

DrawingTools Class

class DrawingTools {
  setTool(tool)                  // Change active tool
  setCategory(categoryId)        // Set drawing category
  clearSelection()               // Deselect all features
  deleteSelected()               // Remove selected features
  getCurrentTool()               // Get active tool name
  getSelectedFeatures()          // Get selection list
}

POI Management (poi.js)

POIManager Class

class POIManager {
  placePOI(position, name, type, properties)
  updatePOI(poiId, updates)      // Modify existing POI
  deletePOI(poiId)               // Remove POI
  showPOIDialog(poi)             // Open edit dialog
  hidePOIDialog()                // Close edit dialog
  getAllPOIs()                   // List all POIs
  getPOIsByType(type)            // Filter by type
}

Storage System (storage.js)

StorageManager Class

class StorageManager {
  saveProject(project, updateMeta)
  loadProject()                  // Load from localStorage
  exportProject(project, filename)
  importProject(file)            // Import from file
  startAutosave(project)         // Begin auto-backup
  stopAutosave()                 // End auto-backup
  getSettings()                  // Load app settings
  saveSettings(settings)         // Save app settings
  isDirty()                      // Check for unsaved changes
}

Pathfinding (pathfinding-worker.js)

PathfindingEngine Class

class PathfindingEngine {
  initializeGrid(features, categories, bounds, resolution)
  findPath(startWorld, endWorld) // Calculate route
  setParameters(params)          // Configure algorithm
  worldToGrid(x, y)              // Convert coordinates
  gridToWorld(gridX, gridY)      // Convert coordinates
}

Canvas Grid (canvas-grid.js)

CanvasGrid Class

class CanvasGrid {
  setGridSpacing(spacing)        // Configure grid
  setGridOrigin(origin)          // Set grid origin
  fitToContent(bounds, padding)  // Auto-zoom to features
  getSnapPosition()              // Get grid-snapped cursor
  screenToWorld(screenX, screenY)
  worldToScreen(worldX, worldY)
  draw()                         // Render canvas
}

Configuration & Settings

Application Settings

Stored in localStorage under key schoolRouteMapper_settings:

{
  theme: 'light',                // 'light' or 'dark'
  gridSpacing: 0.5,              // Default grid spacing (meters)
  autosaveEnabled: true,         // Enable automatic saves
  routingResolution: 0.25,       // Pathfinding grid resolution
  defaultBuffer: 0.3,            // Obstacle clearance distance
  turnPenalty: 0.3,              // Cost for direction changes
  splineTension: 0.5,            // Curve smoothness (0-1)
  animationSpeed: 1.0,           // Route animation speed
  highQualityRendering: true     // Enhanced graphics quality
}

Performance Settings

Grid Configuration

Theme Support

Development & Deployment

Prerequisites

Development Setup

  1. Clone/Download: Obtain source files
  2. Web Server: Serve files from route/ directory
  3. Browser: Open index.html in browser
  4. Development: Edit files directly, refresh to see changes

File Structure

route/
├── index.html              # Main application page
├── debug.html              # Development/testing page
├── test.html               # Unit test page
├── test-canvas.html        # Canvas testing page
├── js/                     # JavaScript modules
│   ├── app.js              # Main application
│   ├── data-model.js       # Data structures
│   ├── canvas-grid.js      # Rendering engine
│   ├── drawing-tools.js    # Interactive tools
│   ├── poi.js              # POI management
│   ├── pathfinding-worker.js # Route calculation
│   ├── storage.js          # Data persistence
│   ├── ui-controls.js      # User interface
│   ├── spline.js           # Curve generation
│   └── demo-data.js        # Sample data
├── styles/                 # CSS stylesheets
│   ├── main.css            # Core styles
│   └── themes.css          # Theme definitions
└── ROUTE_MAPPER_DOCUMENTATION.md # This file

Deployment Options

Static Web Hosting

GitHub Pages

# Push to GitHub repository
git add route/
git commit -m "Deploy School Route Mapper"
git push origin main

# Enable GitHub Pages in repository settings
# Point to route/ folder or root directory

Local Development Server

# Python 3
cd route/
python -m http.server 8000

# Node.js
npx http-server route/ -p 8000

# PHP
cd route/
php -S localhost:8000

Browser Compatibility

Required Browser Features

Performance Considerations

Technical Specifications

Coordinate System

File Format Specifications

.schoolmap.json Schema

Export Capabilities

Performance Metrics

Security Considerations

Accessibility Features

Error Handling

Future Enhancements

Support and Documentation

Getting Help

Contributing

Version History

License

Open source software - check LICENSE file for specific terms and conditions.

This documentation was generated for the School Route Mapper application. For the most current information, please refer to the source code and inline comments.