feat: Add Employee Directory Demo Plugin (2M Records Performance Showcase)

[lane711]

Overview

Import the Edge Cache Demo from the standalone repository into the SonicJS monorepo as a dedicated Employee Directory Demo Plugin. This demo showcases SonicJS's exceptional performance handling large datasets (2M+ records with relations) on Cloudflare's edge infrastructure.

Live Demo: https://edgecache-demo.pages.dev/
Source Repository: https://github.com/lane711/edgecache-demo (to be imported from local /Users/lane/Dev/refs/edgecache-demo)

Motivation

• Performance Showcase: Demonstrates SonicJS handling 2 million employee records with department relations at sub-50ms response times
• Edge Computing Benefits: Shows the speed advantage of edge-cached APIs vs traditional origin servers
• Plugin Architecture Example: Serves as a reference implementation for building demo plugins
• Marketing Asset: Provides tangible performance proof for the SonicJS website and documentation

Proposed Implementation

1. Create Demo Plugin Package

Add a new package at packages/employee-directory-demo/ with the following structure:

packages/employee-directory-demo/
├── package.json
├── README.md
├── src/
│   ├── index.ts              # Plugin export
│   ├── schema/
│   │   └── employees.ts      # Employee + Department schema definitions
│   ├── routes/
│   │   └── employees.ts      # API routes for employee listing
│   ├── seed/
│   │   └── generator.ts      # Seed data generator for 2M records
│   └── frontend/
│       ├── App.tsx           # React demo frontend
│       ├── components/
│       │   ├── Sidebar.tsx
│       │   ├── Persons.tsx
│       │   ├── Stats.tsx
│       │   ├── Pagination.tsx
│       │   └── ...
│       └── index.css
└── demo/
    ├── wrangler.toml         # Cloudflare Pages config
    └── index.html

2. Core Features to Include

Backend (Plugin):

• Employee content type with fields: name, email, avatar, department (relation), region, gender
• Department content type
• Efficient API endpoints with filtering: /api/v1/employees?filters[department][$eq]=Engineering
• Support for pagination: limit, offset query params
• Performance headers: sonicjs-source: cache|origin

Frontend (Demo App):

• Employee grid view with avatar cards
• Sidebar filters: Department, Gender, Region (multi-select)
• Real-time performance stats display (response time in ms)
• Toggle between "Edge Cache" and "Origin" modes to compare speed
• Pagination controls
• API URL display for transparency

3. Current Demo Dependencies

The existing demo uses:

• React 18.3
• Tailwind CSS 3.4
• @headlessui/react 2.1 (for filter UI)
• @heroicons/react 2.1 (for icons)
• Vite 5.4 (bundler)

4. Tasks

• Create packages/employee-directory-demo/ package structure
• Define Employee and Department schemas using SonicJS content types
• Port existing React components from edgecache-demo repo
• Convert JSX to TypeScript/TSX
• Create seed data generator script for populating demo database
• Add deployment configuration for Cloudflare Pages
• Update monorepo workspaces in root package.json
• Add to www site navigation/demo section
• Document plugin usage and deployment steps

5. API Design

Employee Listing Endpoint:

GET /api/v1/employees
Query params:
  - limit (default: 18)
  - offset (default: 0)
  - filters[department][$eq]=<department_name>
  - filters[gender][$eq]=<male|female>
  - filters[region][$eq]=<region_name>

Response:
{
  "data": [...employees],
  "total": 2000000,
  "source": "cache" | "origin"
}

6. Benefits of Plugin Architecture

• Isolated codebase: All demo code lives in one package
• Reusable schema: Other apps can extend or reference the employee data model
• Independent deployment: Demo can be deployed separately to showcase performance
• Test fixture: Useful for performance testing and benchmarking

Additional Considerations

• Should support both D1 (SQLite) and Turso database adapters
• Consider pre-generated sample avatars or use a deterministic avatar service
• May want to add OpenAPI documentation for the demo endpoints

References

• Current live demo: https://edgecache-demo.pages.dev/
• SonicJS Docs: https://sonicjs.com/docs
• Cloudflare Workers: https://developers.cloudflare.com/workers/

---

/cc @lane711