# Running everything

Linux, from the repository root. You need Elixir 1.18 / OTP 27, Node 22, PostgreSQL, and (for the payer app) Flutter. The development
database configuration connects to local PostgreSQL as `postgres` with password `postgres` on port `5432`. Configure PostgreSQL to
accept those credentials, or change the development configuration to match your local setup.

## 1. Start PostgreSQL

On systemd-based distributions:

```bash
sudo systemctl enable --now postgresql
sudo systemctl status postgresql
```

## 2. First-time setup

Run once from the repository root. This fetches dependencies, creates and migrates the three databases, loads the development seed
data (a demo partner and merchant, a demo issuer and two payers, and the switch participants), and builds the assets:

```bash
mix deps.get

(cd apps/bqr_acquirer && mix ecto.create && mix ecto.migrate && mix run priv/repo/seeds.exs)
(cd bqr_switch_sim && mix deps.get && mix ecto.create && mix ecto.migrate && mix run priv/repo/seeds.exs)
(cd apps/bqr_issuer && mix ecto.create && mix ecto.migrate && mix run priv/repo/seeds.exs)

mix assets.setup
mix assets.build
(cd bqr_switch_sim && mix assets.setup && mix assets.build)
```

## 3. Start the three servers

Start all three in the current terminal. Press **Ctrl-C** to stop them:

```bash
./scripts/dev.sh
```

For a phone on the same Wi-Fi, bind the acquirer and issuer to the network as well:

```bash
LAN=1 ./scripts/dev.sh
```

LAN mode exposes the issuer's web screens, which do not require login. Its mobile API still requires the API key. Only use this on a
trusted network, and allow inbound TCP ports `34100` and `34300` in your firewall if needed. The switch stays bound to loopback.

Or start each service in a separate terminal:

```bash
(cd bqr_switch_sim && mix phx.server)       # http://localhost:34200
(cd apps/bqr_acquirer && mix phx.server)    # http://localhost:34100
(cd apps/bqr_issuer && mix phx.server)      # http://localhost:34300
```

For LAN access when starting services individually, set `ACQUIRER_BIND_ALL=1` for the acquirer and `ISSUER_BIND_ALL=1` for the
issuer, for example:

```bash
(cd apps/bqr_issuer && ISSUER_BIND_ALL=1 mix phx.server)
```

Check that all three services and their databases are healthy:

```bash
curl http://localhost:34100/health
curl http://localhost:34200/health
curl http://localhost:34300/health
```

Each should return `{"status":"ok",...,"db":"up"}`.

| System | URL | What |
|---|---|---|
| Acquirer | http://localhost:34100 | Partner API: merchants, QR generation, credits |
| Switch simulator | http://localhost:34200 | Stands in for NPSB |
| Issuer | http://localhost:34300 | Payer web screens and the JSON API used by the mobile app |

## 4. Make a QR (HTML tool)

Open `tools/qr-generator.html` in a browser. Choose **Load my merchants**, select *Dynamic* or *Static*, then choose **Generate QR**.
The page sends signed requests to the acquirer and displays the QR. For a dynamic QR it polls for payment and changes to *used (paid)*
when the payment completes. It uses the seeded development partner (`demo-partner`).

The tool can be opened as a local file because the acquirer allows browser preflight requests in development only.

After editing the source, rebuild the HTML file and run its signing tests:

```bash
node tools/build-qr-generator.mjs
node --test tools/test/signing.test.mjs
```

## 5. Pay with the Flutter app

See [mobile/bqr_payer/README.md](../mobile/bqr_payer/README.md). Start the servers first, then:

```bash
cd mobile/bqr_payer
flutter run -d chrome       # this PC; camera access works on localhost
flutter run                 # connected Android phone or emulator
```

For a phone, start the servers with `LAN=1 ./scripts/dev.sh`. In the app's **Settings**, set the issuer address to
`http://<your Linux machine's Wi-Fi address>:34300`, test the connection, then save. The phone and machine must be on the same Wi-Fi;
allow inbound TCP port `34300` in the Linux firewall if needed. The Android emulator uses `http://10.0.2.2:34300`.

No camera? Use **Paste QR text** in the app and copy the QR payload from the HTML tool.

## 6. Check the payment client from the command line

There is no Bash equivalent of `scripts/e2e.ps1` yet. To exercise the payer API client against the running issuer, generate a QR in
the HTML tool and pass its payload to the Dart smoke test:

```bash
cd mobile/bqr_payer
dart run tool/smoke.dart --qr '<QR text>' --url http://localhost:34300
```

## Tests

Run these from the repository root:

```bash
mix test                                      # umbrella: core, protocol, acquirer, issuer
(cd bqr_switch_sim && mix test)               # switch simulator
(cd mobile/bqr_payer && flutter test)         # Flutter app
node --test tools/test/signing.test.mjs       # HTML tool request signing
```

## PostgreSQL troubleshooting

Check the PostgreSQL service and recent logs:

```bash
sudo systemctl status postgresql
sudo journalctl -u postgresql --since "10 minutes ago"
```

If the database reports that it is still starting or recovering, wait for recovery to finish and check the logs before retrying. For
test runs, `BQR_DB_POOL=3` reduces the connection pool size, and `BQR_DB_PORT=<port>` selects a different PostgreSQL port.