Skip to main content

​
Installation

Complete installation guide for setting up SimulationBank’s Flask backend and React frontend.

​
System Requirements

Backend Requirements

  • Python 3.7 or higher
  • pip (Python package manager)
  • Virtual environment (recommended)

Frontend Requirements

  • Node.js 16 or higher
  • npm 7+ or yarn
  • Modern web browser

​
Project Structure

SimulationBank/
├── backend/
│   ├── src/
│   │   ├── simulation/
│   │   │   └── domain/
│   │   │       ├── simulation.py              # Main DES engine
│   │   │       ├── simulation_config.py       # Configuration dataclass
│   │   │       ├── simulation_event.py        # Event types
│   │   │       └── simulation_status.py       # Status enum
│   │   ├── customer/
│   │   │   ├── domain/
│   │   │   │   ├── customer.py                # Customer entity
│   │   │   │   └── priority.py                # Priority enum
│   │   │   └── infrastructure/
│   │   │       └── poisson_customer_generator.py
│   │   ├── teller/
│   │   │   └── domain/
│   │   │       ├── teller.py                  # Teller entity
│   │   │       └── teller_status.py           # IDLE/BUSY enum
│   │   └── queue/
│   │       └── domain/
│   │           └── priority_queue.py          # Heap-based queue
│   ├── requirements.txt
│   └── app.py                                 # Flask entry point
│
├── frontend/
│   ├── src/
│   │   ├── queue/
│   │   │   ├── components/
│   │   │   │   ├── QueueVisualizer.jsx        # Queue display
│   │   │   │   ├── QueueNode.jsx              # Customer node
│   │   │   │   └── PriorityLegend.jsx         # Color legend
│   │   │   ├── hooks/
│   │   │   │   └── useQueueState.js           # Queue state hook
│   │   │   └── services/
│   │   │       └── queue.api.js               # API calls
│   │   ├── metrics/
│   │   │   ├── components/
│   │   │   │   ├── MetricsDashboard.jsx       # Main dashboard
│   │   │   │   ├── WaitTimeChart.jsx          # Wait time viz
│   │   │   │   ├── ThroughputChart.jsx        # Throughput viz
│   │   │   │   ├── QueueLengthChart.jsx       # Queue size viz
│   │   │   │   └── SaturationReport.jsx       # Utilization
│   │   │   ├── hooks/
│   │   │   │   └── useMetrics.js              # Metrics hook
│   │   │   └── services/
│   │   │       └── metrics.api.js             # API calls
│   │   ├── shared/
│   │   │   └── components/                    # Reusable UI
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js

​
Backend Installation

1

Clone the repository

git clone https://github.com/your-org/SimulationBank.git
cd SimulationBank/backend
2

Create a virtual environment

python3 -m venv venv
source venv/bin/activate
3

Install dependencies

pip install -r requirements.txt
This installs:
requirements.txt
flask
flask-cors
Package details:
  • flask: Lightweight WSGI web framework for the REST API
  • flask-cors: Cross-Origin Resource Sharing support for frontend communication
4

Verify installation

python -c "import flask; print(f'Flask {flask.__version__}')"
Expected output: Flask 2.x.x or higher
5

Run the backend server

python app.py
You should see:
* Running on http://127.0.0.1:5000
* Debug mode: on

​
Backend Configuration

The SimulationConfig dataclass (backend/src/simulation/domain/simulation_config.py:6) defines all configurable parameters: 
@dataclass
class SimulationConfig:
    num_tellers: int = 3  # Number of teller windows
    
    arrival_config: Dict[str, Any] = field(default_factory=lambda: {
        "arrival_rate": 1.0,              # λ (lambda): customers per second
        "arrival_dist": "exponential",    # Distribution type
        "priority_weights": [0.1, 0.3, 0.6]  # [HIGH, MEDIUM, LOW] probabilities
    })
    
    service_config: Dict[str, Any] = field(default_factory=lambda: {
        "service_mean": 5.0,              # μ (mu): average service time (seconds)
        "service_dist": "exponential",    # Distribution type
        "service_stddev": 1.0             # Only used for normal distribution
    })
    
    max_simulation_time: float = 8.0 * 3600  # 8 hours in seconds
    max_queue_capacity: int = 100             # Maximum waiting queue size

​
Backend API Endpoints

Once running, the backend exposes these endpoints:
EndpointMethodDescription
/api/simulation/startPOSTInitialize and start a new simulation
/api/simulation/pausePOSTPause the running simulation
/api/simulation/resumePOSTResume a paused simulation
/api/simulation/stopPOSTStop and finalize the simulation
/api/simulation/statusGETGet current simulation state
/api/metrics/currentGETGet real-time metrics
/api/queue/stateGETGet current queue contents

​
Frontend Installation

1

Navigate to frontend directory

cd frontend
2

Install Node.js dependencies

npm install
3

Verify package.json dependencies

Key dependencies from frontend/package.json:
{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react-swc": "^4.2.2",
    "vite": "^7.3.1",
    "eslint": "^9.39.1"
  }
}
4

Configure API base URL (optional)

If your backend runs on a different port, create a .env file:
.env
VITE_API_BASE_URL=http://localhost:5000
5

Start the development server

npm run dev
Vite will start the server at http://localhost:5173
6

Open in browser

Navigate to http://localhost:5173You should see the SimulationBank interface with:
  • Configuration sliders
  • Start/Pause/Stop controls
  • Queue visualizer
  • Metrics dashboard

​
Frontend Build

For production deployment: 
npm run build
This creates optimized static files in frontend/dist/ that can be served by any static file server.

​
Development Workflow

​
Running Both Servers Simultaneously

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
python app.py

​
Hot Reloading

  • Backend: Flask runs in debug mode by default, auto-reloading on code changes
  • Frontend: Vite provides instant HMR (Hot Module Replacement) for React components

​
Docker Installation (Alternative)

Docker support coming soon. This section will include docker-compose configuration for one-command deployment.

​
Troubleshooting

SimulationBank requires Python 3.7+. Check your version:
python3 --version
If you have multiple Python versions, use:
python3.9 -m venv venv  # Use specific version
Use a virtual environment (recommended) or install with --user:
pip install --user -r requirements.txt
Fix npm permissions:
# Option 1: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node

# Option 2: Fix global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
macOS Monterey and later uses port 5000 for AirPlay. Either:Option 1: Disable AirPlay Receiver in System PreferencesOption 2: Change Flask port in app.py:
if __name__ == '__main__':
    app.run(debug=True, port=5001)  # Use different port
Ensure flask-cors is installed:
pip install flask-cors
Verify it’s initialized in app.py:
from flask_cors import CORS
app = Flask(__name__)
CORS(app)  # Enable CORS for all routes
Ensure you’re in the correct directory and virtual environment:
cd backend
source venv/bin/activate
python -c "import src.simulation.domain.simulation"
If imports fail, check that src/ is in your Python path.

​
Verification

To verify your installation is complete:
1

Backend health check

curl http://localhost:5000/api/simulation/status
Should return JSON with simulation status.
2

Frontend loads

Open http://localhost:5173 - you should see the SimulationBank UI.
3

Run a test simulation

  1. Click “Start Simulation” with default parameters
  2. Verify queue visualizer shows customers
  3. Check that metrics update in real-time
  4. Click “Stop” to end the simulation
If all steps complete successfully, you’re ready to explore SimulationBank! Check out the Quickstart Guide next.

​
Next Steps

Quickstart

Run your first simulation

Configuration

Learn about all configuration options

Simulation Engine

Understand the core DES engine

API Reference

Explore backend API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us