# SpectrumField · Deployment Package

**Domain:** `spectrum.korevra.com`
**Platform:** Spectrum Innovation Technologies · Powered by KorevraField
**Version:** 3.0.0 · build 2026.04.15

A fully functional, client-side field-operations platform purpose-built for distribution businesses operating across Nigeria. Six specialised portals share a single live localStorage database with cross-tab reactivity, so a clock-in on the mobile app updates the manager dashboard in real time, a broadcast from admin pushes to everyone, and a partner order lands in the rewards ledger instantly — with no backend server required.

## The Six Portals

| File | Audience | What it does |
| --- | --- | --- |
| `index.html` | Anyone | Marketing landing page with live stats and portal launcher |
| `mobile.html` | Field staff (all roles) | GPS clock in/out, KPI, leave, expense, PSI stock, eSurvey, eTicket, market intel, rewards, training, directory, notifications |
| `dashboard.html` | Managers, CFO, Admin | Approvals queue, KPI analytics, attendance heat, leaderboards, reports, CSV export |
| `admin.html` | System Admin only | Users, roles, branches, geofences, KPI library, policies, products, surveys, notices, badges, courses, channels, broadcast, audit, backup |
| `portal.html` | Partners / distributors | Catalog, cart, orders, stock, sales, settlements, rewards, promos, assets, messages, tickets, training, account |
| `training.html` | All staff | Course catalog, enrollment, modules, quizzes, certificates, learning leaderboard |
| `map.html` | Managers, Admin | Interactive Leaflet map of 28 branches with geofence rings, region filters, popups |

## The Fourteen Modules

| # | Module | Where it lives | What it does |
| --- | --- | --- | --- |
| 1 | **ePunctuality** | Mobile, Dashboard | GPS clock in/out with 150m geofence, Haversine distance check, selfie hook, approval flow |
| 2 | **eSurvey** | Mobile, Admin | Admin builds surveys, staff respond with photos, analytics roll up by branch/region |
| 3 | **KPI Intelligence** | Mobile, Dashboard, Admin | 14 KPI groups, staff log daily, supervisors approve, CFO sees aggregate trends |
| 4 | **Leave Management** | Mobile, Dashboard | Annual / casual / sick / maternity workflow with balance tracking and approval chain |
| 5 | **Expense Claims** | Mobile, Dashboard | Receipt upload, line items, category codes, manager approval, reimbursement status |
| 6 | **PSI / Stock** | Mobile, Portal, Admin | Opening / purchase / sold / expected / in-transit / closing states across products |
| 7 | **eTicket** | Mobile, Admin | Support ticket creation with priority, SLA, assignment, status lifecycle |
| 8 | **Market Intel** | Mobile, Dashboard | Competitor pricing, shelf share, promo activity, visual merchandising reports |
| 9 | **Rewards / Gamification** | Mobile, Portal, Training | 5-tier system (Bronze→Silver→Gold→Platinum→Diamond), badges, points, leaderboard |
| 10 | **Messaging** | Mobile, Portal, Admin | Broadcast, group, and region channels with attachments and read receipts |
| 11 | **Training Academy** | Mobile, Portal, Training | Courses, modules, quizzes, certificates, completion tracking |
| 12 | **Push Notifications** | All portals | Browser Notification API for instant alerts with targeting rules |
| 13 | **Notice Board** | Mobile, Admin | Company-wide notices with pinned, categorised, scheduled posting |
| 14 | **Staff Directory** | Mobile, Dashboard | Search 174 staff by name / branch / role with call/message actions |

## Authentication

- **OTP Login:** 6-digit code with 10-minute expiry, delivered via SMS channel stub
- **PIN Fallback:** Legacy PIN supported for offline-first field scenarios
- **Password Reset:** Email flow via admin-configurable SMTP (stubbed for demo)
- **Role Gate:** `SXUI.requireAuth({ roles: [...] })` blocks entry per portal
- **Session Store:** Signed token in localStorage, 24-hour default expiry

## Demo Accounts

| ID | PIN | Role | Portal Access |
| --- | --- | --- | --- |
| `ADMIN` | `Spectrum@2026!` | System Admin | **All portals** |
| `SPE101` | `Oyeniran@2026` | CFO (Alalade Oyeniran) | Mobile, Dashboard, Map, Training |
| `SPJ120` | `Yusuf@2026` | Branch Manager (Yusuf Aduragbemi) | Mobile, Dashboard, Map, Training |
| `SPE250` | `Segun@2026` | Team Leader (Igbojuwo Segun) | Mobile, Dashboard, Training |
| Any partner ID | Partner PIN | Partner / Distributor | Portal, Training |

## Local Preview

Open `index.html` in any modern browser, or serve the folder so the service worker + seed fetch work:

```bash
npx serve .                 # port 3000
# or
python -m http.server 8080  # port 8080
```

Then visit `http://localhost:3000/` and pick any portal from the launcher.

## Deployment

### GitHub Pages
Push the contents of this folder to any branch. The `CNAME` file binds the custom subdomain.

### Netlify
```bash
netlify deploy --prod --dir=.
```
`netlify.toml` handles redirects, headers, and PWA rules automatically.

### Vercel
```bash
vercel deploy --prod
```
`vercel.json` handles redirects and headers.

### DNS
Point `spectrum.korevra.com` CNAME at your hosting provider:
- GitHub Pages → `username.github.io`
- Netlify → `your-site.netlify.app`
- Vercel → `cname.vercel-dns.com`

## Navigation Shortcuts

These work on Netlify/Vercel thanks to the redirect rules in `_redirects` and `netlify.toml`:

- `/mobile` → field app
- `/dashboard` → manager portal
- `/admin` → admin console
- `/map` → branch map
- `/portal` or `/partners` → partner portal
- `/training` or `/academy` → training academy

## Architecture

- **No backend.** All data persists to `localStorage` under key `spectrum_db_v3` and syncs across tabs via `storage` events and a custom event bus.
- **Event bus.** `SX.on('db:changed', fn)` reacts to any mutation. Specific events: `attendance:clockIn`, `leave:submitted`, `expense:decided`, `order:placed`, `ticket:raised`, `kpi:logged`, `training:enrolled`, `reward:awarded`, `broadcast:sent`.
- **Seed data.** `data/seed.json` auto-loads on first visit and contains:
  - 28 Nigerian branches (SP101–SP128) across 14 states with real GPS coords
  - 174 staff with IDs, PINs, roles, branches, phones, and avatars
  - 14 KPI groups with targets, weights, and categories
  - 45+ products across 6 categories with pricing and stock levels
  - 6 training courses with 30+ modules and quizzes
  - Sample surveys, notices, tickets, orders, rewards transactions
- **Role-gated routing.** Each portal calls `SXUI.requireAuth({ roles: [...] })`:
  - `mobile` — any authenticated user
  - `dashboard` — admin, cfo, manager, leader, supervisor
  - `admin` — admin only
  - `portal` — partner + admin
  - `map` — any authenticated user
  - `training` — any authenticated user
- **Offline first.** Service worker precaches the full shell (including training academy) and serves `offline.html` when the network is unreachable. localStorage mutations queue and become visible the moment a tab reconnects.
- **Geofencing.** Default 150m radius per branch (configurable per branch in Admin → Geo). Haversine distance check on every clock-in with override + reason capture when out of bounds.
- **Gamification.** 5-tier level system calculated from points:
  - Bronze: 0 – 500
  - Silver: 501 – 1,500
  - Gold: 1,501 – 3,500
  - Platinum: 3,501 – 7,500
  - Diamond: 7,501+

## File Tree

```
deploy/
├── index.html                   # Landing page
├── mobile.html         # Field app (iPhone frame)
├── dashboard.html      # Manager portal
├── admin.html          # Admin console
├── portal.html         # Partner portal
├── training.html       # Training academy (NEW v3)
├── map.html            # Branch map
├── offline.html                 # SW offline fallback
├── 404.html                     # Not-found page
├── manifest.json                # PWA manifest
├── sw.js                        # Service worker v3.0.0
├── favicon.svg                  # Branded icon
├── CNAME                        # Pages subdomain
├── netlify.toml                 # Netlify config
├── vercel.json                  # Vercel config
├── _headers                     # Netlify headers
├── _redirects                   # Netlify redirects
├── robots.txt                   # SEO
├── sitemap.xml                  # SEO
├── data/
│   └── seed.json                # 28 branches, 174 staff, 14 KPIs, etc.
├── assets/
│   ├── spectrum-core.js         # Data layer + event bus
│   ├── spectrum-ui.js           # Shared nav, auth, modal, toast
│   └── spectrum-theme.css       # Dark glassmorphic design system
└── README.md                    # This file
```

## What's New in v3.0.0

- **Training Academy** — full new portal with 6 seed courses, enrollment, modules, quizzes, certificates, and a dedicated learning leaderboard
- **Admin Console 2.0** — 17 pages across 7 sections with full CRUD for users, branches, KPI, products, surveys, notices, badges, courses, channels, and broadcast
- **Partner Portal 2.0** — 13 pages with cart / orders, stock intelligence, settlement ledger, promos, brand assets, messages, support tickets, and training
- **Branch Map 2.0** — region-coloured markers, geofence rings, search, region filter, auto-fit bounds, live staff-count popups
- **Mobile App 2.0** — adds PSI, eSurvey, eTicket, Market Intel, Rewards, Messages, Training, Notifications, Notices, Directory (10 new modules)
- **OTP Authentication** — 6-digit code flow alongside PIN fallback
- **Push Notifications** — Browser Notification API with permission prompt and targeted delivery
- **Gamification 2.0** — 5-tier system, badges, leaderboards surfaced in mobile, portal, and training
- **Geofencing 2.0** — per-branch configurable radius with override + reason capture

---

© 2026 Spectrum Innovation Technologies · Powered by KorevraField