Skip to content

aristotekujialphonse/school_map

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
.github/workflows
.github/workflows
 
 
admin
admin
 
 
api
api
 
 
DOCUMENTATION.md
DOCUMENTATION.md
 
 
README.md
README.md
 
 
config.php
config.php
 
 
index.php
index.php
 
 

Repository files navigation

👥 GROUP INFORMATION

PROJECT NAME: GIS SCHOOL MAP
GROUP LEADER: ARISTOTE ALPHONSE (BSCCS/2025/40882)
LEADER EMAIL: ARISTOTE@STUDYSHARE.ONLINE

📋 TEAM MEMBERS

NO NAME REGISTRATION NUMBER EMAIL ROLE
1 ARISTOTE ALPHONSE BSCCS/2025/40882 ARISTOTE@STUDYSHARE.ONLINE GROUP LEADER
2 ALIER BIOR BSCCS/2025/41621 - MEMBER
3 OBAE DERRICK BSCCS/2025/58185 - MEMBER
4 GRACE GATHONI BBIT/2024/74659 - MEMBER
5 LYN WANJIKU BSCCS/2025/40726 - MEMBER
6 MANORE DAVIS BSCCS/2025/40635 - MEMBER
7 SIMIYU AMY BSCCS/2025/39530 - MEMBER
8 JOSHUA SAMUEL BSCCS/2025/40065 - MEMBER
9 MARIAM STEPHEN BSCCS/2025/39404 - MEMBER
10 ROSEMARY MBUTHIA BSCCS/2025/42787 - MEMBER

MKU Campus Navigator

Interactive Live-Navigation Campus Map for Mount Kenya University — Thika Main Campus General Kago Road, Thika Town, Kiambu County, Kenya · -1.0461678, 37.0856074

PHP MySQL Leaflet License

Table of Contents

  1. Overview
  2. Live Demo Features
  3. Screenshots
  4. System Requirements
  5. Installation
  6. Configuration
  7. Project Structure
  8. Database Schema
  9. API Reference
  10. Admin Panel
  11. Keyboard Shortcuts
  12. Technologies Used
  13. Known Issues & Limitations
  14. Contributing
  15. License

Overview

MKU Campus Navigator is a full-stack, browser-based interactive campus mapping and live navigation system built for the Thika Main Campus of Mount Kenya University. It provides students, staff, and visitors with a real-time, GPS-aware way to explore campus buildings, navigate between locations, and access up-to-date facility information — all without installing a mobile app.

The system combines a PHP/MySQL back-end with a rich Leaflet.js front-end map interface, live weather data from the Open-Meteo API, an image gallery for each building, and a full admin panel for managing locations, images, and categories.

Why it was built

Mount Kenya University's Thika campus spans a large area along General Kago Road and hosts dozens of buildings across multiple academic schools and service departments. New students and visitors frequently struggle to locate specific facilities. This system solves that problem with:

  • True GPS-accurate building positions — coordinates sourced from OpenStreetMap Overpass API building footprint centroids, OSM Way IDs verified (e.g. Library: OSM Way 628149408 → -1.0462363, 37.0858007). True campus GPS center: -1.0461678, 37.0856074
  • Turn-by-turn walking navigation using real road data (OSRM)
  • Voice guidance via the browser Web Speech API
  • Live weather for the Thika area
  • A full admin back-end to add, edit, and manage buildings

Live Demo Features

Feature Description
🗺️ Interactive Map Leaflet.js map centered on actual MKU coordinates
🛰️ 4 Map Layers Light (CartoDB), Dark (CartoDB), Satellite (ESRI), Street (OSM)
📍 Live GPS Real-time user location via navigator.geolocation.watchPosition
🧭 Turn-by-Turn Navigation Route drawn via OSRM; voice instructions via Web Speech API
🏛️ 17 Campus Buildings Real MKU buildings with accurate positions, descriptions, hours, amenities
📸 Image Galleries 3-photo auto-rotating carousel per building
🌤️ Live Weather Current temperature and conditions for Thika via Open-Meteo API
🌙 Dark Mode Full CSS-variable dark theme toggled by button or D key
🔍 Smart Search Fuzzy search across building name, category, description, and amenities
📊 Animated Stats Animated counter cards showing 52k students, 200 programmes, 10 campuses
📰 News Tab Latest MKU campus news and events
ℹ️ About MKU Tab Full university facts, schools list, other campuses, contact info
🔢 Marker Clustering Leaflet.markercluster groups nearby markers at low zoom
⌨️ Keyboard Shortcuts F search, D dark mode, C centre, Esc close, +/- zoom
📋 Deep Links Share a specific building via ?loc=2 URL parameter
🖥️ Fullscreen Mode Browser Fullscreen API button in map controls
📱 Responsive Mobile-friendly layout; sidebar collapses on narrow screens

Screenshots

┌─────────────────────────────────────────────────────────┐
│  [☰] [🧭] [MKU Navigator]  [Search…]  [🌤22°C] [🌙]   │  ← Top Bar
├──────────────────┬──────────────────────────────────────┤
│                  │                                      │
│  [Explore|About  │                                      │
│   MKU | News]    │         LEAFLET MAP                  │
│                  │     (MKU Thika, General Kago Rd)     │
│  Category chips  │                                      │
│                  │                                      │
│  ┌─ Location ──┐ │                                      │
│  │ 🏛 Library  │ │                              [📍]    │
│  │ ⭐4.8 · Lib │ │                              [+]     │
│  │ [View][Nav] │ │                              [-]     │
│  └─────────────┘ │                              [⊙]    │
│                  │                              [🗺]    │
│  ┌─ Location ──┐ │                              [⛶]    │
│  │ 🏥 Clinic   │ │                                      │
│  └─────────────┘ │                                      │
├──────────────────┴──────────────────────────────────────┤
│ 📍 MKU THIKA  ▶  52,000+ Students · General Kago Rd … │  ← Ticker
└─────────────────────────────────────────────────────────┘

System Requirements

Server

Requirement Minimum Recommended
PHP 7.4 8.1+
MySQL 5.7 8.0+
Web Server Apache 2.4 / Nginx Apache 2.4 with mod_rewrite
PHP Extensions pdo, pdo_mysql, fileinfo + mbstring, json
Upload Limit 10 MB (upload_max_filesize) 20 MB
Storage 100 MB 1 GB (for images)

Browser (Client)

Browser Minimum Version
Chrome / Edge 90+
Firefox 88+
Safari 14+
Mobile Chrome 90+

Note: Geolocation and Voice features require HTTPS in production. On localhost they work over plain HTTP.

Installation

1. Clone / Copy the project

# Using git
git clone https://github.com/your-org/mku-campus-navigator.git /var/www/html/mku_campus

# Or copy manually
cp -r mku_campus/ /var/www/html/mku_campus

2. Create the MySQL database

CREATE DATABASE mku_campus_map
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

3. Configure the application

Edit config.php with your database credentials:

define("DB_HOST", "localhost");
define("DB_NAME", "mku_campus_map");
define("DB_USER", "your_db_user");
define("DB_PASS", "your_db_password");

define("SITE_URL", "http://localhost/mku_campus");

⚠️ Security: Never commit config.php with real credentials to a public repository. Add it to .gitignore.

4. Run the auto-setup

The first request to config.php automatically runs CREATE TABLE IF NOT EXISTS statements that build all 7 database tables and seed default categories and amenities. Simply open:

http://localhost/mku_campus/

The tables will be created on the first page load.

5. Create the admin user

Navigate to:

http://localhost/mku_campus/admin/setup.php

This creates the default admin account:

  • Username: admin
  • Password: admin123

⚠️ Change this password immediately after first login in production.

6. Set directory permissions

The uploads folder must be writable by the web server:

chmod -R 755 /var/www/html/mku_campus/uploads/
chown -R www-data:www-data /var/www/html/mku_campus/uploads/

7. Apache Virtual Host (optional)

<VirtualHost *:80>
    ServerName mku-campus.local
    DocumentRoot /var/www/html/mku_campus
    DirectoryIndex index.php

    <Directory /var/www/html/mku_campus>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/mku_campus_error.log
    CustomLog ${APACHE_LOG_DIR}/mku_campus_access.log combined
</VirtualHost>

8. Enable mod_rewrite (Apache)

sudo a2enmod rewrite
sudo systemctl restart apache2

Configuration

All application configuration lives in config.php:

// ── Database ──────────────────────────────────────────
define("DB_HOST",  "localhost");        // MySQL host
define("DB_NAME",  "mku_campus_map");   // Database name
define("DB_USER",  "root");             // MySQL username
define("DB_PASS",  "your_password");    // MySQL password

// ── Application ────────────────────────────────────────
define("SITE_NAME", "MKU Campus Map");
define("SITE_URL",  "http://localhost/mku_campus");

// ── PHP Error Reporting ────────────────────────────────
error_reporting(E_ALL);
ini_set("display_errors", 1);   // Set to 0 in production

Front-end constants (inside index.php <script>)

Constant / Variable Location Purpose
MKU_CENTER initMap() True campus GPS center [-1.0461678, 37.0856074] (OSM Overpass API verified)
CAMPUS_BUILDINGS Top of <script> Array of 17 building objects
BUILDING_IMAGES Top of <script> Map of building ID → 3 photo URLs
MAP_LAYERS Top of <script> 4 Leaflet TileLayer definitions
Open-Meteo URL fetchWeather() Weather API URL with Thika coordinates

Project Structure

mku_campus/
│
├── index.php                  # Main application entry point (map + UI)
├── config.php                 # Database config, PDO setup, table creation
│
├── admin/                     # Password-protected admin panel
│   ├── login.php              # Admin authentication page
│   ├── setup.php              # One-time admin user creation script
│   ├── dashboard.php          # Admin home — stats + quick actions
│   ├── locations.php          # Manage locations (DataTables list + modal form)
│   ├── save_location.php      # POST handler — insert/update location + images
│   ├── images.php             # Manage images per location
│   └── upload_images.php      # POST handler — multi-file image upload
│
├── api/
│   └── get_locations.php      # JSON REST endpoint — returns all locations
│                              #   with amenities, images, avg rating
│
└── uploads/
    └── locations/             # Uploaded building images (auto-created)
        └── *.jpg / *.png …

File responsibilities at a glance

File Layer Responsibility
index.php Front-end + PHP Full map UI, all JS logic, PHP queries categories
config.php Back-end DB credentials, PDO connection, DDL bootstrap
admin/login.php Back-end Session-based authentication
admin/dashboard.php Back-end Admin overview, stats cards
admin/locations.php Back-end CRUD UI for campus buildings
admin/save_location.php Back-end Validates and persists location + uploaded images
admin/upload_images.php Back-end Validates MIME type/size; saves files + DB records
api/get_locations.php API Returns full location JSON with JOINed data

Database Schema

The database mku_campus_map contains 7 tables:

┌──────────────┐       ┌─────────────────────┐
│  categories  │◄──┐   │      locations       │
│──────────────│   │   │─────────────────────│
│ id (PK)      │   └───│ category_id (FK)     │
│ name         │       │ id (PK)              │
│ icon         │       │ name                 │
│ color        │       │ subcategory          │
│ created_at   │       │ code                 │
└──────────────┘       │ description          │
                       │ long_description     │
                       │ hours                │
                       │ floor                │
                       │ accessible (BOOL)    │
                       │ lat (DECIMAL 10,8)   │
                       │ lng (DECIMAL 11,8)   │
                       │ phone                │
                       │ email                │
                       │ website              │
                       │ rating (DECIMAL 2,1) │
                       │ created_at           │
                       │ updated_at           │
                       └──────────┬──────────┘
                                  │
              ┌───────────────────┼──────────────────┐
              ▼                   ▼                  ▼
   ┌──────────────────┐  ┌───────────────┐  ┌────────────┐
   │  location_images │  │    reviews    │  │  location  │
   │──────────────────│  │───────────────│  │ _amenities │
   │ id (PK)          │  │ id (PK)       │  │────────────│
   │ location_id (FK) │  │ location_id   │  │ location_id│
   │ image_url        │  │ author        │  │ amenity_id │
   │ is_primary (BOOL)│  │ rating (1-5)  │  └─────┬──────┘
   │ caption          │  │ comment       │        │
   │ upload_date      │  │ review_date   │        ▼
   └──────────────────┘  │ created_at    │  ┌────────────┐
                         └───────────────┘  │  amenities │
                                            │────────────│
                                            │ id (PK)    │
                                            │ name       │
                                            │ icon       │
                                            └────────────┘

   ┌─────────────────────┐
   │       users         │
   │─────────────────────│
   │ id (PK)             │
   │ username (UNIQUE)   │
   │ email (UNIQUE)      │
   │ password (bcrypt)   │
   │ full_name           │
   │ role (ENUM)         │   ← 'admin' | 'editor' | 'user'
   │ avatar              │
   │ created_at          │
   └─────────────────────┘

Key Relationships

Relationship Type Tables
Location belongs to Category Many-to-One locations → categories
Location has many Images One-to-Many location_images → locations
Location has many Reviews One-to-Many reviews → locations
Location has many Amenities Many-to-Many location_amenities (junction)
Amenity belongs to many Locations Many-to-Many location_amenities (junction)

Default seed data

Categories (7): academic, library, cafe, medical, sports, admin, residence

Amenities (12): WiFi, Parking, Accessible, Elevator, Cafeteria, Library, Computer Lab, Projector, Air Conditioning, Study Room, First Aid, Security

API Reference

GET /api/get_locations.php

Returns all campus locations with full relational data.

Response format:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Main Administration Block",
      "category_id": 6,
      "category_name": "admin",
      "category_icon": "bi-briefcase",
      "category_color": "#0288d1",
      "subcategory": "Vice Chancellor",
      "code": "ADM-01",
      "description": "Main admin building…",
      "long_description": "…",
      "hours": "8:00 AM – 5:00 PM",
      "floor": 3,
      "accessible": true,
      "lat": "-1.04390000",
      "lng": "37.08110000",
      "phone": "+254 709 153 000",
      "email": "info@mku.ac.ke",
      "website": "https://mku.ac.ke",
      "rating": "4.5",
      "review_count": 12,
      "avg_rating": "4.5000",
      "primary_image": "uploads/locations/abc123.jpg",
      "amenities": [
        { "id": 1, "name": "WiFi", "icon": "bi-wifi" },
        { "id": 3, "name": "Accessible", "icon": "bi-person-wheelchair" }
      ],
      "images": [
        {
          "id": 5,
          "location_id": 1,
          "image_url": "uploads/locations/abc123.jpg",
          "is_primary": true,
          "caption": null
        }
      ]
    }
  ]
}

Error response:

{
  "success": false,
  "error": "SQLSTATE[…]: …"
}

Deep-link URL parameter

The main index.php accepts a loc query parameter to auto-open a building's detail panel on load:

http://localhost/mku_campus/?loc=2

This will centre the map on building ID 2 (Library) and open its detail panel automatically.

Admin Panel

The admin panel is located at /admin/ and requires authentication.

Accessing the admin panel

http://localhost/mku_campus/admin/login.php

Default credentials (change immediately in production):

  • Username: admin
  • Password: admin123

Admin pages

Page URL Purpose
Login /admin/login.php Authenticate with username + password
Setup /admin/setup.php One-time: create default admin user
Dashboard /admin/dashboard.php Overview stats + quick action cards
Locations /admin/locations.php Full CRUD for campus buildings
Images /admin/images.php Upload + manage photos per building

Adding a new location

  1. Go to Admin → Locations
  2. Click "Add Location"
  3. Fill in the modal form:
    • Name (required)
    • Category (required — dropdown from categories table)
    • Latitude / Longitude (required — decimal degrees, e.g. -1.0461678; use OSM Overpass API building footprint centroids for accuracy)
    • Description, long description, opening hours, floor, phone, email, website
    • Accessibility checkbox
  4. Upload up to 10 images (JPG/PNG/GIF/WEBP, max 10 MB each)
  5. Click Save

Tip: To get accurate GPS coordinates for a new building, open Google Maps, right-click the building location, and copy the coordinates shown.

Image upload rules

Rule Value
Allowed formats JPG, PNG, GIF, WEBP
Maximum file size 10 MB per image
Storage location uploads/locations/
File naming uniqid() + original extension
Primary image First image uploaded per location is marked is_primary = 1

Keyboard Shortcuts

The main map interface supports the following keyboard shortcuts:

Key Action
F Focus the search bar
D Toggle Dark / Light mode
C Re-centre map on MKU campus
+ or = Zoom in
- Zoom out
L Jump to your GPS location
Esc Close detail panel / stop navigation / close layer panel

Shortcuts are disabled when the cursor is inside an input, select, or textarea.

Technologies Used

Back-end

Technology Version Purpose
PHP 8.x Server-side rendering, form handling, session auth
MySQL 8.x Relational database for all persistent data
PDO Built-in Database abstraction layer with prepared statements

Front-end

Library Version CDN
Leaflet.js 1.9.4 unpkg.com/leaflet
Leaflet Routing Machine 3.2.12 unpkg.com/leaflet-routing-machine
Leaflet.markercluster 1.5.3 unpkg.com/leaflet.markercluster
Material Icons Round Latest fonts.googleapis.com
Inter (font) Latest fonts.googleapis.com

External APIs

API Purpose Auth Required
Open-Meteo Live Thika weather ❌ Free, no key
OSRM (router.project-osrm.org) Turn-by-turn walking routes ❌ Free, no key
CartoDB tile layers Light + dark map tiles ❌ Free, no key
ESRI World Imagery Satellite tile layer ❌ Free for non-commercial
OpenStreetMap Street map tile layer ❌ Free, attribution required
Unsplash Building photo URLs ❌ Free (no-upload embed)

Admin panel

Technology Version Purpose
Bootstrap Icons 1.11.3 Icon set throughout admin
DataTables 1.13 Sortable/searchable locations table

Known Issues & Limitations

Issue Notes
OSRM routing on campus OSRM uses public road data. Paths entirely inside the campus may not perfectly follow internal walkways — building-to-building routes may route around the campus perimeter
GPS accuracy indoors watchPosition accuracy on mobile degrades inside buildings; a ±20m tolerance is applied
Voice guidance on iOS Safari on iOS sometimes truncates long SpeechSynthesisUtterance texts. Short instruction phrases work reliably
Geolocation over HTTP In production on a public server, geolocation requires HTTPS. The browser will silently deny permission over plain HTTP
ESRI satellite tiles ESRI World Imagery tiles are free for non-commercial use only. For a commercial deployment, replace with a paid provider
Campus boundary polygon OSM-derived bounding rectangle: N -1.0427, S -1.0495, W 37.0825, E 37.0893. Used for boundary checks; does not trace the precise cadastral boundary of the MKU plot
Static building images Building images in BUILDING_IMAGES are Unsplash stock photos, not actual photographs of MKU buildings. Replace with real photos via the admin panel
Admin CSRF The admin panel form handlers do not yet include CSRF token validation. Add before public deployment

Security Notes

Before deploying to a public server:

  1. Change default admin password via the admin panel or direct SQL: 
    UPDATE users SET password = '$2y$10$...' WHERE username = 'admin';
  2. Set display_errors = 0 in config.php: 
    ini_set("display_errors", 0);
  3. Move config.php above the web root or protect it with .htaccess: 
    <Files "config.php">
    Require all denied
</Files>
  4. Remove admin/setup.php after first use.
  5. Use HTTPS — required for geolocation on mobile browsers.
  6. Add CSRF tokens to all admin POST forms.
  7. Restrict uploads/ execution via .htaccess: 
    <Directory /var/www/html/mku_campus/uploads>
    php_flag engine off
</Directory>

Contributing

Contributions are welcome. Please follow these steps:

  1. Fork the repository
  2. Create a feature branch 
    git checkout -b feature/your-feature-name
  3. Commit your changes with a clear message 
    git commit -m "feat: add floor-plan overlay for Block A"
  4. Push and open a Pull Request

Coding conventions

  • PHP: PSR-12 style, all queries use PDO prepared statements
  • JavaScript: ES2020+, const/let, async/await for API calls
  • CSS: CSS custom properties (var(--primary)) for all colours and spacing
  • All GPS coordinates must be confirmed from at least two independent sources

Acknowledgements

  • Mount Kenya University — for campus data and institutional information
  • OpenStreetMap contributors — map base layer data
  • OSRM Project — open-source routing engine
  • Open-Meteo — free open-source weather API
  • Leaflet.js — open-source interactive map library
  • Unsplash photographers — stock building photography

License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 MKU Campus Navigator Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Contact

Mount Kenya University — Thika Main Campus General Kago Road, P.O. Box 342-01000, Thika, Kenya

Channel Detail
Telephone +254 709 153 000
Email info@mku.ac.ke
Website www.mku.ac.ke
💬WhatsApp +254 722 999 399

Documentation last updated: 2025 · MKU Campus Navigator v2.0

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages