# Webapp Reference

The web application is a focused Monte Carlo comparison built with FastAPI,
vanilla JavaScript, and Plotly.js.

## Purpose

For each simulated price path, the backend constructs an adaptive schedule
using the current distance to the nearer log-price barrier and the local
symmetric-endpoint Brownian-bridge proxy. The fixed baseline has two modes:

1. **Equal budget:** use exactly the adaptive schedule's sample count on each
   path, distributed uniformly.
2. **Fixed cadence:** sample at an independently selected interval in minutes,
   with the start and end of the window included.

Lower and upper barrier events are evaluated independently. A detection must
occur within the configured number of simulation-grid steps and the sampled
price must still be beyond the relevant barrier.

## Routes

### `GET /`

Serves the single-page frontend and replaces static asset query strings with
mtime/size cache-busting values.

### `GET /api/health`

Returns runtime readiness, package version, and default model parameters.

### `POST /api/simulate`

Validated request fields include:

- initial price, annual drift, and annual volatility;
- simulation horizon, number of paths, and grid resolution;
- lower and upper barrier percentages;
- local diffusion parameter `eps`;
- hard maximum polling interval;
- detection deadline in grid steps;
- comparison mode and fixed cadence in minutes;
- optional Merton jump parameters;
- optional random seed.

The response contains path data, both schedules, direction-specific breach and
detection fields, exact sample totals, detection-lag summaries, and an explicit
model-scope warning.

## Important interpretation

`eps` is **not** an unconditional probability guarantee. The exact Brownian
bridge formula conditions on two endpoints, whereas an online scheduler does
not know the future endpoint. The implementation substitutes the current
barrier distance for both endpoint distances. Jumps are outside that diffusion
calculation entirely.

The demo therefore presents a controlled scheduling comparison, not a promise
that adaptive sampling always outperforms fixed sampling.

## Frontend

The interface provides controls for all main simulation and detector parameters.
It displays:

- simulated paths and both barriers;
- adaptive observations as open cyan circles;
- equal-budget or fixed-cadence observations as grey dots;
- first lower and upper breach markers;
- direction-specific detection counts;
- exact adaptive/fixed sample totals;
- adaptive and fixed mean detection lags;
- raw run statistics and model-scope warnings.

Pure GBM is the default. Merton jump diffusion is an optional stress mode and
triggers an on-screen warning about the limits of the Brownian proxy.

## Local development

```bash
pip install -e ".[webapp]"
uvicorn webapp.app:app --reload --host 127.0.0.1 --port 8055
```

## API smoke test

```bash
curl -s http://127.0.0.1:8055/api/health
```
