# fwrock/hyperbolic-time-chamber architecture

> Architecture diagram of the GitHub repository fwrock/hyperbolic-time-chamber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fwrock/hyperbolic-time-chamber
- Repository: https://github.com/fwrock/hyperbolic-time-chamber

## Overview

##### Project type and purpose
- HTC-Simulator is an open-source, actor-based, multi-agent discrete-event simulation framework written in Scala, using Apache Pekko (Akka).
- It loads simulation configurations (JSON), instantiates and manages actors, orchestrates events over simulated time, supports reporting, snapshot, and distributed execution via Kafka, Cassandra, and Redis.

##### Top-level structure & architectural patterns
- Top-level files: Dockerfile, build.sbt, shell scripts (CLI entrypoints), application.conf.
- src/main/protobuf: message schemas (entities, events, data models).
- src/main/scala: three main packages:
- core – the simulation engine (HyperbolicTimeChamber, actor managers, event & state machinery, serialization, utilities)
- model – plug-in domains (mobility, supermarket) containing domain-specific actor definitions, entity/state/event classes
- system – runtime services (actor system bootstrap, Kafka broker integration, Cassandra & Redis persistence)
- Config files: application.conf, logback.xml, Docker Compose for local orchestration.
- Architectural patterns:
- Actor Model – all simulation logic is encapsulated in Pekko (Akka) actors.
- Event-driven / discrete-event simulation – TimeManager schedules ticks and dispatches events.
- Layered design – Core engine, domain models, infrastructure services.
- Plugin-style extensibility – new models can be dropped under model/.

##### Main components & their relationships
A. Configuration & Initialization
- JSON simulation config + actor data files → Config Loader (in Core)
- Protobuf schemas define message contracts → ProtobufSerializer
- build-and-run.sh / docker-compose.yml start the entire stack

B. Core Simulation Engine
- HyperbolicTimeChamber (entry point)
- Manager actors (subclasses of BaseManager):
- LoadDataManager – reads actor definitions, spawns BaseActor instances
- SimulationManager – coordinates start/stop of simulation
- TimeManager – advances simulation time, emits tick events
- SnapshotManager – takes/restores state snapshots
- ReportManager – formats and routes simulation results
- DataFlowManager, DigitalTwinManager, MLManager (in development)
- BaseActor – handles domain events (SpontaneousEvent, ActorInteractionEvent)

C. Domain Model Actors
- model/mobility actors (Bus, Car, TrafficSignal, etc.)
- model/supermarket actors (Client, Cashier, etc.)
- Each actor has associated State, Event, and utility classes

D. Infrastructure / System Services
- Actor System bootstrap – BaseActorSystem
- Message Broker – KafkaPublisher & KafkaSubscriber; PublisherConfiguration / SubscriberConfiguration
- Persistence –
- CassandraEntityManager (via CassandraConnection) for event or state storage
- RedisClientManager for caching or ephemeral coordination
- Reporting backends – CsvReportData, JsonReportData, CassandraReportData

- Input Layer
- Core Simulation Layer
- Domain Model Layer
- Infrastructure Layer
- Input Layer: “JSON Config Files”, “Protobuf Schemas”
- Domain: “Mobility Actors”, “Supermarket Actors”
- Infra: “Kafka Cluster”, “Cassandra Cluster”, “Redis Cache”, “BaseActorSystem”

##### Interactions & data flows
- TimeManager → emits Tick Events → Manager Actors → dispatch to BaseActors
- BaseActors → generate Events → may be serialized by ProtobufSerializer → published to Kafka → consumed by other nodes (for distributed sim)
- SnapshotManager → writes state to Redis (or Cassandra)
- ReportManager → writes results to Cassandra or CSV/JSON sinks

##### Important patterns & technologies
- Protobuf message contracts (annotate the link between actors & broker)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        JSONConfig["JSON Config Files"]:::input
        ProtobufSchemas["Protobuf Schemas"]:::input
        DockerCompose["Docker Compose"]:::input
        BuildRun["Build & Run Script"]:::input
    end

    %% Core Simulation Layer
    subgraph "Core Simulation Layer"
        ConfigLoader["Configuration Loader"]:::core
        ProtobufSerializer["Protobuf Serializer"]:::core
        HyperbolicTimeChamber["HyperbolicTimeChamber"]:::core
        subgraph "Manager Actors"
            BaseManager["BaseManager"]:::core
            LoadDataManager["LoadDataManager"]:::core
            SimulationManager["SimulationManager"]:::core
            TimeManager["TimeManager"]:::core
            SnapshotManager["SnapshotManager"]:::core
            ReportManager["ReportManager"]:::core
            DataFlowManager["DataFlowManager"]:::core
            DigitalTwinManager["DigitalTwinManager"]:::core
            MachineLearningManager["MachineLearningManager"]:::core
        end
        BaseActor["BaseActor"]:::core
    end

    %% Domain Model Layer
    subgraph "Domain Model Layer"
        MobilityActors["Mobility Domain Actors"]:::domain
        SupermarketActors["Supermarket Domain Actors"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        BaseActorSystem["BaseActorSystem"]:::infra
        KafkaCluster["Kafka Cluster"]:::infra
        CassandraDB[(Cassandra Cluster)]:::infra
        RedisCache[(Redis Cache)]:::infra
        PublisherConfig["PublisherConfiguration"]:::infra
        SubscriberConfig["SubscriberConfiguration"]:::infra
        CassandraEntityManager["CassandraEntityManager"]:::infra
        CassandraConnection["CassandraConnection"]:::infra
        RedisClientManager["RedisClientManager"]:::infra
        KafkaPublisher["KafkaPublisher"]:::infra
        KafkaSubscriber["KafkaSubscriber"]:::infra
        CsvReportData["CsvReportData"]:::infra
        JsonReportData["JsonReportData"]:::infra
        CassandraReportData["CassandraReportData"]:::infra
    end

    %% Connections
    JSONConfig -->|loads| ConfigLoader
    ProtobufSchemas -->|defines messages| ProtobufSerializer
    DockerCompose -->|orchestrates| KafkaCluster
    DockerCompose -->|orchestrates| CassandraDB
    DockerCompose -->|orchestrates| RedisCache
    BuildRun -->|starts| HyperbolicTimeChamber

    ConfigLoader -->|spawns| LoadDataManager
    HyperbolicTimeChamber -->|entry point| SimulationManager
    BaseActorSystem -->|bootstraps| HyperbolicTimeChamber

    SimulationManager -->|start signal| TimeManager
    TimeManager -->|tick events| BaseActor
    LoadDataManager -->|creates| BaseActor

    BaseActor -->|generates events| ProtobufSerializer
    ProtobufSerializer -->|publishes| KafkaPublisher
    KafkaPublisher -->|to broker| KafkaCluster
    KafkaCluster -->|to subscriber| KafkaSubscriber
    KafkaSubscriber -->|feeds| BaseActor

    SnapshotManager -->|writes state| RedisCache
    SnapshotManager -->|writes state| CassandraDB

    ReportManager -->|writes| CsvReportData
    ReportManager -->|writes| JsonReportData
    ReportManager -->|writes| CassandraReportData

    %% Click Events
    click ConfigLoader "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/load/strategy/JsonLoadData.scala"
    click ProtobufSerializer "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/serializer/ProtobufSerializer.scala"
    click HyperbolicTimeChamber "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/HyperbolicTimeChamber.scala"
    click BaseActor "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/BaseActor.scala"
    click BaseManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/BaseManager.scala"
    click LoadDataManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/LoadDataManager.scala"
    click SimulationManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/SimulationManager.scala"
    click TimeManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/TimeManager.scala"
    click SnapshotManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/SnapshotManager.scala"
    click ReportManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/ReportManager.scala"
    click DataFlowManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/DataFlowManager.scala"
    click DigitalTwinManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/DigitalTwinManager.scala"
    click MachineLearningManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/MachineLearningManager.scala"
    click CsvReportData "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/report/CsvReportData.scala"
    click JsonReportData "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/report/JsonReportData.scala"
    click CassandraReportData "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/core/actor/manager/report/CassandraReportData.scala"
    click MobilityActors "https://github.com/fwrock/hyperbolic-time-chamber/tree/main/src/main/scala/model/mobility/actor/"
    click SupermarketActors "https://github.com/fwrock/hyperbolic-time-chamber/tree/main/src/main/scala/model/supermarket/actor/"
    click BaseActorSystem "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/actor/BaseActorSystem.scala"
    click KafkaPublisher "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/broker/kafka/publisher/KafkaPublisher.scala"
    click KafkaSubscriber "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/broker/kafka/subscriber/KafkaSubscriber.scala"
    click PublisherConfig "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/broker/kafka/configuration/publisher/PublisherConfiguration.scala"
    click SubscriberConfig "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/broker/kafka/configuration/subscriber/SubscriberConfiguration.scala"
    click CassandraEntityManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/database/cassandra/actor/CassandraEntityManager.scala"
    click CassandraConnection "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/database/cassandra/connection/CassandraConnection.scala"
    click RedisClientManager "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/src/main/scala/system/database/redis/RedisClientManager.scala"
    click ProtobufSchemas "https://github.com/fwrock/hyperbolic-time-chamber/tree/main/src/main/protobuf/"
    click DockerCompose "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/docker-compose.yml"
    click BuildRun "https://github.com/fwrock/hyperbolic-time-chamber/blob/main/build-and-run.sh"

    %% Styles
    classDef core fill:#d0e1f9,stroke:#4d648d,color:#000;
    classDef domain fill:#d1e8d1,stroke:#4b8b3b,color:#000;
    classDef infra fill:#fcf4d9,stroke:#d0b118,color:#000;
    classDef input fill:#e0e0e0,stroke:#888888,color:#000;
```
