# Pyrk Walking Club Full Starter System — Pro Upgrade

This AMPPS-ready PHP/MySQL starter now combines the full Pyrk walking club system with:

- Real Google Maps route drawing UI
- Google Routes API walking-route calculation through PHP
- QR member check-in scanner UI
- SMTP email reminder service hooks
- WhatsApp Cloud API reminder hooks
- Production security hardening starter layer
- Photo upload, selfie capture, approval, voting, and winner rewards

## Included modules

- Member registration: name, mobile, email, emergency number, medical conditions, date of birth, gender, photo consent
- Pyrk admin interface and client interface
- Route builder with Google Maps markers, checkpoints, stations, draggable points, route polyline, distance, and duration
- Scheduled walks with date, start time, expected finish time, capacity, registration deadline, waiver requirement, and QR token
- Waiver templates and digital waiver signing
- Walk registration
- Attendance tracing with manual check-in, QR check-in, finish confirmation, verified kilometers, emergency list, and medical notes
- Loyalty points and badge rules
- Member QR code page
- Photo upload from mobile camera/gallery
- Browser selfie capture from webcam
- Photo registration against a walk
- Admin approval/rejection of photos
- Member voting with one vote per walk
- No self-voting
- Photo contest closing and automatic winner selection
- Winner loyalty reward and badge
- Reminder cron job with email / WhatsApp / in-app channels
- Reports dashboard
- Rate limiting, hardened session cookies, security headers, upload protections, audit logging starter

## Technical stack

- AMPPS / Apache
- PHP 8.1+
- MySQL 8+ recommended
- PDO prepared statements
- HTML5
- Modern JavaScript with Fetch API
- Google Maps JavaScript API
- Google Routes API
- QR scanner UI through `html5-qrcode` CDN
- QR generation through `qrcodejs` CDN
- Optional SMTP through PHPMailer
- Optional WhatsApp reminders through Meta WhatsApp Cloud API

## Installation on AMPPS

1. Copy the folder `pyrk_walking_club_full_starter` into your AMPPS web root.

   macOS usually:

   ```text
   /Applications/AMPPS/www/
   ```

   Windows usually:

   ```text
   C:\Program Files\Ampps\www\
   ```

2. Create a MySQL database named:

   ```text
   pyrk_walking_club
   ```

3. Import:

   ```text
   database/schema.sql
   database/seed.sql
   ```

4. Copy:

   ```text
   config/app.example.php
   ```

   to:

   ```text
   config/app.php
   ```

5. Edit the database password inside `config/app.php`.

6. Make these folders writable by Apache/PHP:

   ```text
   public/uploads/photos
   public/uploads/thumbnails
   storage/logs
   ```

7. Open:

   ```text
   http://localhost/pyrk_walking_club_full_starter/public/login-dev.php
   ```

## Demo users

All demo users use password:

```text
password
```

Accounts:

```text
admin@pyrk.local      Super Admin
manager@pyrk.local    Event Manager
leader@pyrk.local     Walk Leader
neo@pyrk.local        Member
lina@pyrk.local       Member
karim@pyrk.local      Member
```

## Google Maps setup

In `config/app.php`, set:

```php
'google' => [
    'maps_browser_key' => 'YOUR_GOOGLE_MAPS_BROWSER_KEY',
    'routes_server_key' => 'YOUR_GOOGLE_ROUTES_SERVER_KEY',
    'default_center' => ['lat' => 33.8938, 'lng' => 35.5018],
],
```

Enable these Google APIs in your Google Cloud project:

```text
Maps JavaScript API
Routes API
```

Recommended key restrictions:

```text
Browser key: restrict by HTTP referrer
Server key: restrict by server IP and Routes API only
```

Route-builder flow:

1. Login as Admin or Manager.
2. Go to Admin > Routes.
3. Click point type: Start, Checkpoint, Water, Medical, Finish.
4. Click the map to add points.
5. Drag markers to adjust.
6. Click Calculate walking route.
7. Save route.

If the Google Routes server key is missing, the system falls back to a direct-line distance estimate so you can still test locally.

## QR check-in setup

Client side:

1. Login as a member.
2. Open Client > My QR.
3. Show this QR to the walk leader.

Admin side:

1. Login as Admin, Manager, or Walk Leader.
2. Go to Admin > Attendance.
3. Select the walk.
4. Click Start QR scanner.
5. Scan the member QR.

Camera access works on `localhost` for development. Production should use HTTPS.

If the QR scanner CDN does not load, use the manual QR token fallback on the same page.

## SMTP email reminders

The default mail driver is `log`, so reminders are written to:

```text
storage/logs/notifications.log
```

To send real email:

1. Install PHPMailer:

   ```bash
   composer require phpmailer/phpmailer
   ```

2. Edit `config/app.php`:

   ```php
   'mail' => [
       'from_email' => 'club@yourdomain.com',
       'from_name' => 'Pyrk Walking Club',
       'driver' => 'smtp',
       'smtp' => [
           'host' => 'smtp.yourdomain.com',
           'port' => 587,
           'username' => 'smtp-user',
           'password' => 'smtp-password',
           'encryption' => 'tls',
       ],
   ],
   ```

## WhatsApp reminders

The project includes a WhatsApp Cloud API sender in `app/Services/NotificationService.php`.

In `config/app.php`:

```php
'whatsapp' => [
    'enabled' => true,
    'driver' => 'cloud_api',
    'phone_number_id' => 'YOUR_PHONE_NUMBER_ID',
    'access_token' => 'YOUR_ACCESS_TOKEN',
    'api_version' => 'v23.0',
],
'reminders' => [
    'channels' => ['email', 'whatsapp', 'in_app'],
    'hours_before_walk' => 24,
],
```

Member mobile numbers should be stored in international format, for example:

```text
+96170123456
```

## Cron jobs

Run manually first:

```bash
php cron/send_walk_reminders.php
php cron/calculate_badges.php
php cron/close_photo_voting.php
```

Then connect to cron or Windows Task Scheduler.

Example Linux cron:

```cron
0 * * * * /usr/bin/php /path/to/pyrk_walking_club_full_starter/cron/send_walk_reminders.php
*/30 * * * * /usr/bin/php /path/to/pyrk_walking_club_full_starter/cron/close_photo_voting.php
```

## Photo + selfie voting flow

1. Login as member.
2. Register for a walk.
3. Sign waiver.
4. Check in.
5. Upload a photo or use Open selfie camera.
6. Admin approves the photo.
7. Other members vote.
8. Admin closes the contest.
9. Winner gets Photo Contest Winner badge and loyalty points.

## Existing database upgrade

If you already imported the older package, run:

```text
database/migrations/002_pro_features.sql
```

For a clean install, just import `schema.sql` then `seed.sql`.

## Production hardening checklist

Before going live:

- Set `env` to `production` in `config/app.php`.
- Set `debug` to `false`.
- Enable HTTPS.
- Set `security.force_https` to `true`.
- Set `security.secure_cookies` to `true`.
- Remove or protect `login-dev.php`.
- Use real SMTP credentials.
- Use HTTPS-only production domain for camera, QR scanner, and selfie capture.
- Restrict Google API keys.
- Restrict Meta/WhatsApp access token permissions.
- Move uploaded files outside public web root or serve through signed PHP endpoints.
- Add virus/malware scanning for uploaded images.
- Add privacy policy, waiver/legal review, and data retention rules.
- Schedule daily database backups.
- Test restore from backup.
- Review emergency/medical-data access permissions.

## Folder guide

```text
api/                  JSON endpoints used by AJAX
app/Core/             database, auth, CSRF, response, security helpers
app/Services/         route, attendance, notification, loyalty, upload, voting services
composer.json         optional PHPMailer dependency
database/             schema, demo seed data, migrations
cron/                 scheduled jobs
public/               browser-facing pages
public/admin/         Pyrk admin interface
public/assets/js/     client/admin JavaScript
public/assets/css/    styling
public/uploads/       starter upload folder
storage/logs/         notification logs and app logs
```

## Free map testing mode: OpenStreetMap + Leaflet

This package now defaults to `maps.provider = osm`, so you can test route maps immediately without Google Maps billing or API keys.

Read:

```text
docs/OPENSTREETMAP_LEAFLET_SETUP.md
```

For production, review OpenStreetMap tile usage limits and use a proper tile/routing provider if your traffic grows.

## Menu/dropdown upgrade

This package includes a polished responsive navigation bar with dropdown sections:

- Client dropdown: upcoming walks, member QR, badges/loyalty, walk history.
- Admin dropdown: route builder, walks, QR attendance, members, photo contest.
- Mobile hamburger menu.
- Active page highlighting.

Main files:

```text
public/partials/nav.php
public/assets/css/app.css
```

Every public/admin page now calls:

```php
<?php pyrk_render_nav('client'); ?>
```

or:

```php
<?php pyrk_render_nav('admin'); ?>
```

## Management upgrade added

This package includes the improved admin/client management screens:

- Admin > Community > Users & Members: create users, create members, edit profile details, assign roles, set emergency/medical data, update passwords, and filter the directory.
- Admin > Events > Routes: create and edit routes, see route cards, view saved points, filter routes, and update checkpoints/stations.
- Admin dashboard: cleaner KPI cards, shortcuts, upcoming walks, pending photos, top walkers, and recent members.
- Client dashboard: upgraded hero, progress panel, upcoming walk cards, badges, QR shortcut, and walk history.

To create a member:

1. Login as `admin@pyrk.local` or `manager@pyrk.local`.
2. Open `Admin > Community > Users & Members`.
3. Fill the Create User form.
4. Choose role `Member`.
5. Add date of birth, emergency contact, medical notes, and photo consent.
6. Click Save User.

To edit a route:

1. Login as admin or event manager.
2. Open `Admin > Events > Routes`.
3. Click `Edit route` on any route card.
4. Update route details or drag/add/remove map points.
5. Click `Calculate distance` and then `Save route`.

## Enterprise CRM upgrade in this package

This package separates staff/system accounts from walking-club members.

### System users

Use this page for Pyrk internal accounts only:

```text
Admin > Community > System users
public/admin/users.php
```

System users include:

```text
Super Admin
Event Manager
Walk Leader
```

Only Super Admin can create or edit system users.

### Members

Use this page for client/member accounts:

```text
Admin > Community > Members
public/admin/members.php
```

Members include the walking-club profile fields:

```text
Date of birth
Gender
Emergency contact
Medical conditions
Photo consent
Total walks
Total kilometers
Loyalty points
Profile picture
```

### Profile photo uploads

Both System users and Members support profile pictures.

Writable folder required:

```text
public/uploads/avatars
```

Accepted types:

```text
JPG
PNG
WEBP
```

Max default size:

```text
4 MB
```

You can change this in:

```php
'uploads' => [
    'avatar_dir' => __DIR__ . '/../public/uploads/avatars',
    'max_avatar_mb' => 4,
]
```

### Upgrading an existing database

If you already imported an earlier package, run this migration:

```text
database/migrations/003_enterprise_users_members.sql
```

For a new clean install, import only:

```text
database/schema.sql
database/seed.sql
```

