# Simulator

The BACEN PIX Simulator enables testing of PIX flows without a real connection to the Central Bank.

## Prerequisites

- `SIMULATOR_ENABLED=true` in environment variables
- `BACEN_ENABLED=false` (simulator replaces real BACEN communication)
- Backend running and healthy

::: danger PRODUCTION WARNING
Never enable the simulator in production. It overrides real BACEN communication behavior.
:::

## Architecture

The `Shared.Bacen.Simulator` GenServer is started conditionally in the `Shared.Application` supervision tree when `SIMULATOR_ENABLED=true`.

```mermaid
graph TB
    API[Simulator API<br/>/api/v1/simulator] --> GS[Simulator GenServer]
    GS --> DICT[Simulated DICT]
    GS --> SPI[Simulated SPI]
    GS --> SCEN[Scenario Engine]
```

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/simulator/status` | Simulator status and configuration |
| PUT | `/api/v1/simulator/config` | Update simulator settings |
| POST | `/api/v1/simulator/process` | Process a simulated message |
| POST | `/api/v1/simulator/inbound` | Simulate inbound message from BACEN |
| GET | `/api/v1/simulator/scenarios` | List available scenarios |
| POST | `/api/v1/simulator/scenarios/:id/run` | Execute a scenario |
| GET | `/api/v1/simulator/test-runs` | List test run results |
| GET | `/api/v1/simulator/test-runs/:id` | Get test run details |
| GET | `/api/v1/simulator/exchanges` | List message exchanges |

## Pre-Configured Scenarios

| Scenario | Description |
|----------|-------------|
| `happy_path` | Successful PIX payment end-to-end |
| `rejected_payment` | Payment rejected by creditor institution |
| `return_flow` | Full return (pacs.004) flow |
| `incoming_payment` | Receive inbound PIX payment |
| `echo_test` | BACEN connectivity test (pibr.001/002) |
| `balance_check` | Settlement balance inquiry (camt.060) |
| `full_cycle` | Complete cycle: send + receive + settle |
| `stress_test` | High-volume transaction burst |

## Running a Scenario

```bash
# List scenarios
curl http://localhost:4003/api/v1/simulator/scenarios

# Run happy_path
curl -X POST http://localhost:4003/api/v1/simulator/scenarios/happy_path/run \
  -H "Content-Type: application/json" \
  -H "Cookie: pix_session=YOUR_JWT"

# Check results
curl http://localhost:4003/api/v1/simulator/test-runs
```

## Integration Testing

The simulator supports full integration tests:

- 200 transactions tested: 100 send (MONETARIE -> MW) + 100 receive (MW -> MONETARIE)
- Settlement delta: 300-1500ms (ANS compliant)
- Status distribution: 85-90% STLD, 5-10% ACSP, 5% PDNG

### Simulated Data

| Data | Count |
|------|-------|
| DICT entries | 20 |
| SPI balances | 12 |
| Scenarios | 10 |
| Simulator configs | 10 |

## Security Notes

- `SimulatorController` uses `String.to_existing_atom` with a whitelist to prevent atom table DoS
- `sanitize_for_json` handles Decimal, DateTime, NaiveDateTime, and struct types safely

## Expected Outcome

After enabling the simulator:

- 8 scenarios available for testing
- DICT lookups return simulated data
- SPI messages processed without BACEN connectivity
- Integration tests pass (200/200 SUCCESS)
- Test run results stored in `bacen_simulator` schema