simulation/

Simulation Service

The Simulation Service generates realistic demo traffic for the Nivo platform. It simulates multiple user personas with different transaction patterns to demonstrate the system's capabilities.

Features

• User Personas: Six distinct user behavior patterns
• Realistic Traffic: Time-based activity with configurable patterns
• Auto-Start: Optional automatic simulation on service start
• Gateway Integration: Uses the API Gateway for all operations
• Controllable: Start/stop simulation via API

API Endpoints

Get Simulation Status

GET /api/v1/simulation/status

Response:

{
  "running": true,
  "message": "Simulation is running"
}

Start Simulation

POST /api/v1/simulation/start

Response:

{
  "message": "simulation started"
}

Stop Simulation

POST /api/v1/simulation/stop

Response:

{
  "message": "simulation stopped"
}

Health Check

GET /health

User Personas

The simulation engine supports six distinct user personas:

Frequent Trader

High-frequency small transactions, typical day trader behavior.

Saver

Conservative user who primarily deposits with rare withdrawals.

Bill Payer

Regular user making scheduled payments.

Shopper

Frequent payments user, typical e-commerce customer.

Investor

Large deposit user making strategic transfers.

Casual

Random sporadic activity typical of occasional users.

Configuration

Environment Variables

Auto-Start Behavior

When AUTO_START_SIMULATION=true:

1. Service waits 10 seconds for other services to initialize
2. Loads seeded users from database
3. Assigns random personas to users
4. Begins generating traffic based on persona schedules

Setup

Prerequisites

• Go 1.23+
• PostgreSQL 14+
• Running Gateway service
• Seeded user accounts (via Seed Service)
• Valid admin JWT token

Running the Service

# Set required environment
export GATEWAY_URL=http://localhost:8000
export ADMIN_TOKEN=eyJhbGciOiJIUzI1NiIs...

# Run
cd services/simulation
go run cmd/server/main.go

Docker Compose

simulation:
  build:
    context: .
    dockerfile: services/simulation/Dockerfile
  environment:
    - GATEWAY_URL=http://gateway:8000
    - ADMIN_TOKEN=${ADMIN_TOKEN}
    - AUTO_START_SIMULATION=true
    - DATABASE_PASSWORD=${DATABASE_PASSWORD}
    - JWT_SECRET=${JWT_SECRET}
  depends_on:
    - gateway
    - seed

Architecture

services/simulation/
├── cmd/
│   └── server/          # Server entry point
├── internal/
│   ├── handler/         # HTTP handlers
│   │   └── simulation_handler.go
│   ├── service/         # Core logic
│   │   ├── simulator.go
│   │   ├── user_lifecycle.go
│   │   └── gateway_client.go
│   └── personas/        # User behavior patterns
│       └── personas.go
├── Makefile
└── README.md

How It Works

1. User Selection: Loads seeded users from database
2. Persona Assignment: Randomly assigns a persona to each user
3. Activity Loop: For each user:
   • Check if current hour is in persona's active hours
   • Check if enough time passed since last transaction
   • Check if balance meets minimum threshold
   • Generate appropriate transaction based on weights
4. Auto-Deposit: If balance drops below threshold, generates a deposit
5. Gateway Calls: All operations go through Gateway API

Monitoring

The simulation generates logs for each action:

[simulation] Started simulation with 5 users
[simulation] [user-123] Persona: frequent_trader, Balance: ₹10,000
[simulation] [user-123] Generated transfer: ₹250 to user-456
[simulation] [user-789] Balance low (₹800), generating deposit
[simulation] [user-789] Generated deposit: ₹5,000

Future Enhancements

• Web UI for simulation control
• Real-time metrics dashboard
• Configurable persona parameters via API
• Load testing mode
• Scheduled simulation windows