solvice/scheduler-plugin
🗓️ Build dispatch scheduler UIs with Claude Code

---

A Claude Code plugin that interactively generates VRP scheduler frontend views — maps, timelines, drag-and-drop dispatch dashboards — using the Solvice API.

⚡ Quick Start

claude plugin add github:solvice/scheduler-plugin

Then in any project:

/scheduler

The plugin walks you through an interactive flow:

🔍 Discovery → What's your use case? Tech stack? Domain language?

📐 Design → Proposes architecture with domain mapping. You approve.

🏗️ Generate → Scaffolds a complete runnable project in your framework.

✅ Validate → Builds it, starts the dev server, confirms it works.

---

🧩 What It Builds

Feature	Description
🗺️ Map view	Job markers, resource depots, route polylines (MapLibre GL JS, Leaflet, or Mapbox)
📊 Timeline view	Gantt-style resource rows with draggable job blocks
🖱️ Drag-and-drop	Reassign jobs between resources with cascaded arrival recomputation
⚡ Real-time evaluation	Two-tier metrics — instant local estimate + server confirmation
🚨 Constraint visualization	Time window, skill, shift, and capacity violations
📈 KPI dashboard	Travel time, distance, cost with delta indicators
⌨️ Keyboard shortcuts	Arrow navigation, pin, unschedule, undo, save
🔧 Exception engine	Actionable diagnostics with auto-fix suggestions
🔀 Scenario testing	What-if analysis with 9 mutation types
📦 Batch operations	Multi-select pin, move, unschedule
🔄 Reoptimize	Re-solve with pinned jobs locked in place
👁️ Drag preview	O(1) impact metrics shown during drag hover

---

🌐 Solvice API Endpoints

The generated code connects to these Solvice API endpoints:

Endpoint	Method	Why
routing.solvice.io/table/sync	POST	📏 Distance matrix — precompute NxN travel times and distances between all job/resource locations. Powers instant drag-and-drop metrics, route polylines, and Tier 1 local evaluation.
api.solvice.io/v2/vrp/solve	POST	🧠 Optimize — submit a full VRP problem for the solver to find the best assignment of jobs to resources. Used for initial schedule generation and reoptimization with pinned jobs. Async: returns a job ID, poll for results.
api.solvice.io/v2/vrp/jobs/{id}/status	GET	⏳ Poll — check solve progress (QUEUED → SOLVING → SOLVED).
api.solvice.io/v2/vrp/jobs/{id}/solution	GET	📥 Fetch solution — retrieve the optimized schedule once the solve completes.
api.solvice.io/v2/vrp/evaluate/sync	POST	✅ Evaluate — score a dispatcher's manual edits in real-time. Returns travel time, distance, cost, and constraint violations without re-solving. This is the Tier 2 server evaluation that confirms the local estimate.
api.solvice.io/v2/vrp/suggest/sync	POST	💡 Suggest — "where should I put this job?" Get ranked placement suggestions for an unassigned job, considering all existing assignments. Powers the exception engine's auto-fix suggestions.

🔑 Auth: All endpoints use Authorization: <SOLVICE_API_KEY> (no Bearer prefix — the key is sent directly).

⚠️ Coordinate gotcha: The routing API uses [longitude, latitude] arrays. The solver API uses { latitude, longitude } objects. The generated code handles this mapping automatically.

---

🛠️ Supported Frameworks

Framework	Status
⚛️ React / Next.js	✅ Supported
💚 Vue 3	✅ Supported
🅰️ Angular	✅ Supported
📜 Vanilla JS / TypeScript	✅ Supported

All generated code uses your domain language — "Work Orders" and "Technicians" instead of generic "Jobs" and "Resources". 🏷️

---

🏗️ How It Works

Three layers:

1. 📚 Skills — Baked-in knowledge of the Solvice VRP API, proven UI patterns, and framework-specific code generation guidelines
2. 📝 Reference implementations — TypeScript types, API call examples, and algorithm snippets distilled from a production scheduler
3. 🤖 Agent — An interactive scheduler-architect that drives discovery, proposes an architecture, generates code, and validates the build

🔄 Extending

Come back later and ask to add features:

Add a map view to my scheduler
Add drag-and-drop support
Add scenario testing

The agent reads your existing code and extends it — never regenerates from scratch. 🧠

---

📁 Plugin Architecture

solvice-scheduler-plugin/
├── 🤖 agents/scheduler-architect.md    # Interactive orchestrator
├── ⚡ commands/scheduler.md            # /scheduler entry point
├── 📚 skills/
│   ├── solvice-vrp-api/                # API endpoints, auth, gotchas
│   ├── scheduler-patterns/             # 16 proven UI patterns
│   └── code-generation/                # Framework-specific conventions
├── 📝 reference/
│   ├── types.ts                        # Canonical VRP TypeScript types
│   ├── api-examples.ts                 # Working fetch calls for all endpoints
│   └── snippets/                       # Algorithm implementations
│       ├── distance-matrix.ts
│       ├── drag-and-drop.ts
│       ├── drag-preview-delta.ts
│       ├── two-tier-evaluation.ts
│       ├── map-integration.ts
│       ├── keyboard-shortcuts.ts
│       ├── exception-engine.ts
│       ├── scenario-testing.ts
│       ├── batch-operations.ts
│       └── reoptimize.ts
├── 🔔 hooks/                           # Auto-detect Solvice projects
└── 🌐 .mcp.json                        # Live docs via context7

---

🎬 See It In Action

solvice/example-field-service — An HVAC field service app that goes from basic tables to a full dispatch dashboard. Two git tags show the before (v0-before) and after (v1-after).

---

🔗 Related

Repo	Purpose
solvice/scheduler-plugin (this)	Build scheduler frontend views — maps, timelines, drag-and-drop dashboards
solvice/agent-plugin	Build scheduling AI agents — auto-assign, reoptimize, what-if, violations
solvice/example-field-service	Example — HVAC field service app, before & after the scheduler plugin

---

📋 Requirements

• Claude Code CLI
• A Solvice API key — get one at solvice.io 🔑

📄 License

MIT