---
title: FlowPilot | Operations Digital Twin
emoji: 📈
colorFrom: green
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Operations simulation and staffing decision studio
tags:
  - operations-research
  - simulation
  - monte-carlo
  - decision-support
  - optimization
  - analytics
  - javascript
---

> **Verified single-file application:** FlowPilot includes its HTML, CSS, simulation engine and user interface in `index.html`. No server runtime, paid hosting or external JavaScript packages are required.


# FlowPilot | Operations Digital Twin

**Reproducible staffing analysis, queue modeling and cost-aware decision support, right in your browser.**

[Launch the application](https://huggingface.co/spaces/Hugdrigo/flowpilot-operations-lab)

![FlowPilot preview](https://img.shields.io/badge/Project-23-52dfb6?style=flat-square) ![SDK](https://img.shields.io/badge/Space-Static-567ac8?style=flat-square) ![License](https://img.shields.io/badge/License-MIT-informational?style=flat-square) ![Dependencies](https://img.shields.io/badge/Runtime%20dependencies-0-2bbaa0?style=flat-square)

> **Important:** This is a simulated operations planning sandbox, **not a trained machine-learning model, AI predictor or a production-grade forecasting service**. All example inputs are hypothetical. Decisions must be validated with real operational data.

## What it does

| Capability | Description |
| --- | --- |
| **Queue simulation** | Simulates an 8-hour service shift using hourly Poisson arrivals, triangular service durations, a first-come-first-served queue and fixed customer patience. |
| **Staffing optimizer** | Compares staffing levels from 1 to a configurable maximum (20). Identifies the lowest *mean total cost* among options satisfying a *mean service-level target*. |
| **Common-random-number comparisons** | Every candidate staffing level sees the exact same simulated customer arrivals and service durations within a replication. |
| **Uncertainty summaries** | Shows 10th and 90th percentiles across replications for shift cost, SLA attainment and abandoned customers. |
| **Cost accounting** | Calculates scheduled wages, time-worked overtime wages, cost of waiting and estimated loss per abandonment. |
| **Import and export** | Imports demand CSVs or scenario JSON; exports a reproducible JSON report, CSV comparison and scenario JSON. |
| **Privacy-first design** | No backend, authentication, telemetry, API keys, CDN or external data requests are required for operation. |

## Explore the example scenarios

1. **Retail & customer service:** pronounced midday demand peaks, relatively short interactions.
2. **Healthcare reception:** moderate arrivals but longer service interactions and a stricter quality target.
3. **Technical support:** longer interactions, evening demand peaks and mixed labor costs.

Example figures are **fictional, not observed business data**.

## How to use

1. Choose a template or load your own scenario (`.json`).
2. Edit staff members, service times, patience, hourly expected arrivals, service-level threshold and cost parameters.
3. Click **Run simulation**.
4. Read the **Performance snapshot**, cost frontier, service-level curve and uncertainty summary.
5. Review the **Recommended strategy** and detailed staffing comparison.
6. Export the report or apply the proposed staffing count to test the counterfactual as your new baseline.

**Demand CSV format** (8 data rows required):

```csv
hour,arrivals
1,12
2,16
3,24
4,40
5,33
6,26
7,18
8,10
```

Hours may be indexed 1–8 or 0–7. Arrival rates are expected customer counts per hour and can be fractional. The optimizer assumes a fixed number of staff through the shift, not dynamic per-hour staffing.

## Model definition

### Arrival process

For each one-hour segment, customer arrivals follow a homogeneous Poisson process with rate `hourlyArrivals[h] / 60` per minute, sampled by exponential interarrival times. Different hours can have different rates, creating an eight-step nonstationary demand curve.

### Service process

Every arriving customer is given a service duration sampled independently from a triangular distribution with `minimum ≤ most likely ≤ maximum` minutes. An identical customer cohort is reused when comparing alternative staff counts.

### Queue discipline and patience

Customers are served first-come-first-served by the earliest available staff member. A customer abandons before service starts if waiting time exceeds a user-provided patience threshold. All customers have the same threshold. In-progress service is not interrupted, including when the shift ends.

### Service-level calculation

```
SLA attainment = arrivals who begin service within SLA waiting time / all arrivals
```

Abandoned customers are counted as misses. When there are zero arrivals, SLA is defined as 100% in the model by convention; this is not an observed quality result.

### Total shift cost

```
scheduled labor = staff × 8 hours × hourly wage
post-close labor = sum of active service minutes after closing / 60 × hourly wage × 1.5
waiting cost = (served-customer wait minutes + abandonment patience minutes) × cost per waiting minute
abandonment cost = abandoned customers × cost per abandoned customer

total modeled cost = scheduled labor + post-close labor + waiting cost + abandonment cost
```

The overtime multiplier of 1.5 is a modeling choice, not a legal payroll rule. Currency is labeled illustrative USD, but the tool does not apply any FX conversion.

### Monte Carlo optimization

For each replication `r`, a deterministic random seed derived from the scenario's seed is used to sample one customer cohort. The optimizer compares all staff counts against the *same* sampled cohort. Metrics are averaged across replications. A staff count is feasible when its **average** simulated SLA meets or exceeds the target. From these feasible choices, the tool picks the lowest average modeled total cost (ties favor fewer staff).

**This does not assert that any specific real-world shift has a guaranteed probability of meeting the SLA.** The P10–P90 band displays dispersion across simulation runs, not a formal confidence interval. Service-time assumptions, no-shows, shift variability and costs should be calibrated against observed data.

## Implementation

- **Frontend:** HTML5, CSS3 and native JavaScript modules.
- **Compute:** Plain JavaScript; client-side deterministic discrete-event simulation.
- **Deployment:** Hugging Face **Static Space**, without builds or backend dependencies.
- **Data handling:** Imports/exports processed in browser; does not transfer information to a server.
- **Compatibility:** Modern desktop and mobile browsers supporting native ES modules, file inputs and Blob downloads.

### Repository files

```
README.md          Space configuration and technical documentation
index.html         Accessible application layout
styles.css         Responsive light/dark interface
core.mjs           Pure deterministic queue simulation, statistics and optimizer
presets.mjs        Three clearly labeled hypothetical example scenarios
app.mjs            UI interactions, data import/export and SVG charts
LICENSE            MIT open-source license
```

### Local development

Static assets must be loaded from a local web server, not opened as an ordinary `file://` page, because ES modules are subject to browser security rules.

```bash
python3 -m http.server 7860
# Navigate to http://localhost:7860
```

### Automated tests

The complete development package also includes:

```bash
node --test tests/core.test.mjs
python tests/ui_smoke.py
```

The test suite covers seeded reproducibility, FCFS waiting order, abandonment, cost accounting, overtime, input validation, CSV import/export, staffing optimization and no feasible recommendation. A Chromium-based smoke test checks actual interactions, charts, mobile rendering and download workflows. The browser test harness in restricted environments inlines assets for inspection, while the published files remain separate native modules.

## Limitations and responsible use

- A simplified **FCFS queue with fixed staffing and identical patience** cannot capture every real-world service system.
- The model deliberately excludes appointment schedules, priorities, breaks, arrivals after closing, time-varying staff, multi-stage routing and customer heterogeneity.
- Cost parameters, especially lost-customer and waiting costs, are **assumptions**, not audited financial figures.
- Replication percentiles are descriptive simulation outputs and are **not** statistical confidence intervals.
- A comparison using common random numbers reduces avoidable sampling noise but does not establish causal effects in external real-world operations.
- Results are not guarantees, medical advice, financial advice or employment recommendations.

## Portfolio relevance

This project demonstrates operations research, stochastic simulation, reproducibility, optimization under service constraints, JavaScript application architecture, input validation, explainable decision support, quality assurance and responsible disclosure of modeling assumptions.

**Maintainer:** [Hugdrigo](https://huggingface.co/Hugdrigo)  
**License:** MIT