Architecture Overview

​

Architectural Pattern

• Clean separation of concerns
• Testability and maintainability
• Technology independence at the core
• Clear dependency flow from outside-in

​

System Architecture

​

Layer Responsibilities

​

Domain Layer (Core)

• Entities: Customer, Teller, DiscreteEventSimulation
• Value Objects: SimulationConfig, Priority, TransactionType
• Domain Events: SimulationEvent with event types
• Ports: Interfaces like CustomerGenerator, MetricsRepository

​

Application Layer

• run_simulation.py - Execute simulation
• generate_customer.py - Create customer instances
• record_customer_served.py - Track metrics
• get_simulation_report.py - Generate reports

​

Infrastructure Layer

• HTTP Adapters: Flask blueprints and controllers
• Generators: ConfigurableGenerator (Poisson distribution)
• Persistence: InMemoryMetricsRepository
• Frontend: React components and state management

​

Bounded Contexts

​

Dependency Rule

Infrastructure → Application → Domain

• Domain layer depends on nothing
• Application layer depends only on domain
• Infrastructure layer depends on both application and domain

​

Technology Stack

​

Backend

• Language: Python 3.x
• Web Framework: Flask
• CORS: flask-cors
• Event Queue: Python heapq (min-heap)
• Random Generation: NumPy (exponential distribution)

​

Frontend

• Language: JavaScript (ES6+)
• Framework: React 19.x
• Build Tool: Vite 7.x
• State Management: React hooks (useState, useEffect)
• HTTP Client: Fetch API

​

Directory Structure

SimulationBank/
├── backend/
│   ├── main.py
│   ├── requirements.txt
│   └── src/
│       ├── simulation/
│       │   ├── domain/
│       │   ├── application/
│       │   └── infrastructure/
│       ├── customer/
│       ├── teller/
│       ├── queue/
│       ├── metrics/
│       └── shared/
└── frontend/
    ├── package.json
    ├── index.html
    └── src/
        ├── simulation/
        ├── customer/
        ├── teller/
        ├── queue/
        ├── metrics/
        └── shared/

​

Design Principles

​

Separation of Concerns

• Simulation manages time and event processing
• Customer handles arrival and service logic
• Teller manages resource allocation
• Queue implements priority ordering
• Metrics tracks performance indicators

​

Dependency Inversion

# Domain defines the interface
class CustomerGenerator(ABC):
    @abstractmethod
    def get_next_arrival_interval(self) -> float:
        pass

# Infrastructure implements it
class ConfigurableGenerator(CustomerGenerator):
    def get_next_arrival_interval(self) -> float:
        return np.random.exponential(1.0 / self.arrival_rate)

​

Immutability

@dataclass(frozen=True)
class SimulationConfig:
    num_tellers: int = 3
    arrival_config: Dict[str, Any] = field(default_factory=dict)
    service_config: Dict[str, Any] = field(default_factory=dict)

​

Communication Patterns

​

Frontend ↔ Backend

• Protocol: HTTP/REST
• Format: JSON
• CORS: Enabled for local development

​

Event Flow

1. Frontend sends configuration via POST /api/simulation/start
2. Backend creates DiscreteEventSimulation instance
3. Simulation processes events in chronological order
4. Frontend polls GET /api/simulation/state for updates
5. Metrics accumulate in MetricsRepository
6. Frontend fetches GET /api/metrics/report for analysis

​

Next Steps