# Nimbus Cloud Simulator - VM + LB API Traffic Imitation Guide

This guide explains how to imitate cloud traffic behavior with the new split architecture:
- React frontend in `frontend/`
- Flask simulation backend in `backend/`

All cloud logic is in Python (`backend/simulator.py`) and split services under `backend/services/`.

## 1) Run both services

Start backend:

```bash
cd backend
python -m pip install -r requirements.txt
python app.py
```

Start frontend in another terminal:

```bash
cd frontend
npm install
npm run dev
```

Open `http://localhost:5173`.

Optional CLI usage (instead of UI):

```bash
cd backend
python cli.py health
python cli.py state --summary
```

## 2) Create backend VMs

In **Step 1: Create VM**:
1. Enter VM name, region, machine type, and image.
2. Choose VM runtime mode:
   - `profile` (profile-only simulation)
   - `python_script` (runs real python script process per VM)
3. If using `python_script`, set script path (for example `scripts/sample_app.py`).
4. Choose a backend profile.
3. Click **Provision VM**.

Flask backend simulates per VM:
- Reserved backend port (`7000+`)
- API routes from selected profile
- `100 requests/cycle` VM capacity
- Provisioning -> running transition
- For `python_script` mode: starts script process on that VM port and logs output to `backend/logs/script_vm_<vmid>.log`

## 3) Create load balancer

In **Step 2: Create Load Balancer**:
1. Enter LB name, type, and region.
2. Choose request distribution algorithm:
   - `round_robin`
   - `weighted_round_robin`
   - `least_connections`
   - `random`
3. Choose one of 3 scale profiles:
   - `conservative`
   - `balanced`
   - `aggressive`
4. Choose queue tier (`disabled` / `paid`) and Cloud Armor policy.
2. Select running VMs as backends.
5. Click **Create Load Balancer**.

Flask backend simulates per LB:
- Reserved frontend port (`9000+`)
- Type-based request cap:
  - `HTTP(S)`: `800 requests/cycle`
  - `TCP`: `1500 requests/cycle`
- Distribution algorithm based request routing
- Scale-up and scale-down behavior based on selected profile
- Queue tier behavior and Cloud Armor rate limiting

## 4) Simulate API traffic

In **Step 3: Simulate API Requests**:
1. Choose active LB.
2. Choose endpoint.
3. Enter request burst count and client id.
4. Send traffic.

Backend enforces limits in order:
1. Cloud Armor basic checks + rate limit.
2. LB cap first.
2. VM/API compatible pool cap second.
3. Served requests are distributed by selected LB algorithm.
4. Queue tier stores overflow (paid queue can grow with autoscaled VM count).

Auto scaling behavior:
- If VM/API overflow exists, backend auto-creates VM clones on new ports and attaches them to the LB.
- Scale-down removes autoscaled VMs during low-utilization idle cycles.
- The autoscale cap is profile max VM count per LB.
- Once max is reached, remaining overflow is queued or dropped.
- Logs include distribution monitor lines with algorithm, cursor, autoscaled-now/total, scaled-down-now, queue depth, and per-VM distribution.
- For script-mode templates, autoscaled VMs launch the same script on new ports to imitate VM clone behavior.

## 5) Understand monitoring output

If LB cap is exceeded:
- Message says to upgrade/increase LB capacity.

If VM/API pool is exceeded:
- Message says to add/upgrade VMs.

If no rejection:
- Message confirms successful handling and reports estimated latency.

## 6) Where to modify backend logic

Edit backend service files:
- `backend/services/constants.py` for profiles, limits, and catalogs.
- `backend/services/load_balancer_service.py` for distribution algorithms.
- `backend/services/autoscaler_service.py` for scale-up and scale-down behavior.
- `backend/services/request_queue_service.py` for queue behavior.
- `backend/services/cloud_armor_service.py` for rate limiting/basic checks.
- `backend/services/script_runtime_service.py` for VM python script lifecycle.
- `backend/services/postgres_service.py` for online PostgreSQL query execution.
- `backend/services/mongo_service.py` for online MongoDB operations.

Frontend (`frontend/src/App.jsx`) should stay as API client + UI only.

## 8) Online PostgreSQL in UI

Backend exposes:
- `GET /api/sql/status`
- `POST /api/sql/execute`

To enable:
1. Set `DATABASE_URL` before starting backend.
2. Use the frontend SQL console (Step 4) to execute queries.

Notes:
- Query results are capped by `MAX_SQL_ROWS` (`backend/services/constants.py`).
- If `DATABASE_URL` is missing, SQL service stays disabled.

## 9) Online MongoDB in UI

Backend exposes:
- `GET /api/mongo/status`
- `POST /api/mongo/execute`

To enable:
1. Set `MONGODB_URI` before starting backend.
2. Set `MONGODB_DB` if the database is not included in your URI.
3. Use the frontend Mongo console (Step 5) to run `find`, `insert_one`, `update_one`, `delete_one`, and `count_documents`.

Notes:
- Mongo `find` results are capped by `MAX_MONGO_DOCS` (`backend/services/constants.py`).
- If `MONGODB_URI` is missing, Mongo service stays disabled.

## 10) Quick verification scenario

1. Create 2 VMs with same profile.
2. Create one HTTP(S) LB with both VMs.
3. Send 500 requests to `GET /health` -> expected no rejection.
4. Send 1200 requests to `GET /health` -> expected LB rejection.
5. Use one backend VM and send 800 requests -> expected VM/API rejection.
