Skip to main content

System Architecture

Overview​

Boxme Levelling runs as a Cloudflare Workers edge application using the Hono framework. Static assets are served via CDN, and the backend connects to Supabase (PostgreSQL).

Architecture Diagram​

┌─────────────────────────────────────────────────────────────┐
│                     Cloudflare Edge Network                  │
│                                                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              Cloudflare Pages / Workers                │  │
│  │                                                         │  │
│  │  ┌──────────────┐    ┌──────────────────────────────┐ │  │
│  │  │  Static Files│    │     Hono Backend (Worker)    │ │  │
│  │  │  /static/*   │    │                              │ │  │
│  │  │  app.js      │    │  /api/auth/*                 │ │  │
│  │  │  styles.css  │    │  /api/dashboard/*            │ │  │
│  │  └──────────────┘    │  /api/employees/*            │ │  │
│  │                       │  /api/violations/*           │ │  │
│  │                       │  /api/recovery/*             │ │  │
│  │                       │  /api/bonuses/*              │ │  │
│  │                       │  /api/scores/*               │ │  │
│  │                       │  /api/benefits/*             │ │  │
│  │                       │  /api/config/*               │ │  │
│  │                       │  /api/export/*               │ │  │
│  │                       └──────────────┬───────────────┘ │  │
│  └──────────────────────────────────────┼───────────────── │  │
│                                         │                    │
│                              ┌──────────▼──────────┐        │
│                              │   Supabase (PG)     │        │
│                              │   PostgreSQL DB     │        │
│                              └─────────────────────┘        │
└─────────────────────────────────────────────────────────────┘

Request Flow​

Browser → Cloudflare CDN → Pages Worker (Hono)
                                   ↓
                          Route matching:
                          /api/* → API handler → Supabase DB
                          /*     → HTML shell (SPA)
                          /static/* → Static files

Project Structure​

boxme_levelling/
├── src/
│   ├── index.tsx          # Main entry, CORS, static, SPA shell
│   ├── routes/
│   │   └── api.ts         # All 80+ API routes
│   └── types/
│       └── index.ts       # TypeScript Bindings type
├── public/
│   └── static/
│       ├── app.js         # SPA (~5,000 lines)
│       ├── styles.css     # Custom CSS
│       └── swagger.yaml   # OpenAPI spec
├── migrations/
│   ├── 0001_initial_schema.sql
│   ├── 0002_seed_data.sql
│   ├── 0003_policy_update_2026.sql
│   ├── 0004_recovery_enhanced.sql
│   └── 0005_skill_courses.sql
├── docs-site/             # ← This documentation site
├── wrangler.jsonc
├── vite.config.ts
└── package.json

Database Tables​

Organization​

  • countries — Country registry with timezone
  • warehouses — Warehouse locations per country
  • staff_groups — Staff groupings per warehouse (Inbound/Outbound/Value-added)
  • employees — Employee master data
  • users — Login credentials and roles

Configuration​

  • pph_threshold_config — PPH performance level thresholds
  • violation_type_config — Violation type definitions with penalty points
  • violation_level_config — Penalty accumulation → severity mapping
  • bonus_type_config — Bonus categories
  • skill_courses — Training courses for recovery
  • course_violation_links — Auto-assignment of courses to violation types
  • work_hour_standard_config — Standard hours per country
  • benefit_rule_config — Benefit eligibility conditions
  • compensation_support_config — Company support percentages
  • pph_multiplier_config — PPH level multipliers for bonuses

Operational​

  • pph_daily_raw — Daily PPH data from WMS
  • violation_records — Individual violation instances
  • bonus_records — Bonus point records
  • recovery_records — Recovery/training records
  • employee_period_scores — Aggregated period scores
  • approval_requests — Approval workflow queue
  • config_audit_log — Audit trail for config changes