# psmon/kopring-reactive-labs architecture

> Architecture diagram of the GitHub repository psmon/kopring-reactive-labs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psmon/kopring-reactive-labs
- Repository: https://github.com/psmon/kopring-reactive-labs

## Overview

##### Project Type and Purpose
- This is a full-stack reactive application:
- A .NET Blazor front-end (BlazorWebApp) serving the UI and invoking APIs via HTTP, SSE, and WebSockets.
- A Kotlin + Spring WebFlux + Akka Actor back-end (KotlinBootReactiveLabs) exposing REST/SSE/WS endpoints, running an actor system for concurrency, and persisting state via R2DBC.
- A Kotlin-based shared model library (CommonModel) used to define message DTOs and domain objects consistently on both sides.

##### File Structure
- Top-level modules:
- BlazorWebApp – UI layer in C#/.razor files; JS utilities for SSE & WebSocket; CSS assets.
- CommonModel – Kotlin Gradle project packaging shared data models (SendTextMessage, ChatModels).
- KotlinBootReactiveLabs – Spring Boot WebFlux application with Akka actor packages (core, cluster, persistence, router, sse, stream, timer, etc.), controllers (actor, cluster, auth, pubsub, sse), service layer, repository layer, configs, and resources.

##### README for Insights
- The system leverages:
- Reactive Streams (Reactor) for non-blocking data flows.
- Spring WebFlux as the HTTP/SSE/WS server.
- R2DBC for reactive database access.
- Akka Actor model for concurrency, distribution, and CQRS (Event Sourcing, Snapshots, Durable State, Akka Projections).
- Docker-based test environments for MySQL, Postgres, Mongo, Kafka, RabbitMQ, Redis.

a. Client Tier
- Browser/mobile client running Blazor WebApp (HTML/CSS/JS/razor components).
- JS libraries for SSE and WebSocket (in wwwroot/js).
b. API Gateway / HTTP Layer
- Spring WebFlux server hosting controllers:
- REST endpoints (ActorController, ClusterController, AuthController, Admin controllers).
- SSE endpoint (SseController).
- WebSocket endpoints (ReactiveWebSocketConfig + WS handlers under ws/actor).
- Pub/Sub API (PubSubController).
c. Business Layer
- Service classes (SendService, SimpleAuthService) orchestrating use cases.
- Akka Actor System (multiple actor packages: core, cluster, discovery, persistent, router, sse, state, stream, supervisor, timer).
- CQRS components: Event Journal, Snapshot store, Durable State Store, Projections.
d. Data Layer
- R2DBC drivers connecting to relational DBs (Postgres/MySQL) for event journals and durable state.
- DAO/DTO layers under repositories/durable.
e. Shared Model Library
- CommonModel JAR distributed as Gradle dependency to backend, and shared via Protobuf/JSON contracts to Blazor front-end (via JsonUtil.cs).
f. External Systems (optional)
- Kafka, RabbitMQ, Redis (used in tests or in production for Pub/Sub, if configured).

##### Relationships and Data Flows
- Controller → Service → Actor System (tell/ask patterns).
- Actors → Event Journal / Durable Store (R2DBC) → Database.
- Actors → Projections → Read model (R2DBC) → Query API.
- Controller → SSE / WS push → Client.

##### Architectural Patterns
- Non-blocking Reactive Streams end-to-end.
- Actor Model for concurrency, distribution, resilience (supervisors, clustering).
- CQRS: segregation of write model (Akka Persistence) and read model (Akka Projections + R2DBC).
- Layered architecture: Presentation (Blazor/Controllers), Business (Services/Actors), Persistence (Repositories/DB).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        C1["Blazor WebApp UI"]:::frontend
        C2["JS SSE & WebSocket Utilities"]:::frontend
        C3["JsonUtil.cs"]:::frontend
    end

    %% Shared Model
    subgraph "Shared Model Library"
        SM["CommonModel DTOs & Models"]:::shared
    end

    %% API Layer
    subgraph "API Gateway / HTTP Layer"
        A0["Spring WebFlux API"]:::backend
        A1["ActorController (REST)"]:::backend
        A2["ClusterController"]:::backend
        A3["AuthController"]:::backend
        A4["Admin Controllers"]:::backend
        A5["ChatController (Dummy)"]:::backend
        A6["PubSubController"]:::backend
        A7["SseController"]:::backend
        A8["ReactiveWebSocketConfig & Handlers"]:::backend
    end

    %% Business Layer
    subgraph "Business Layer"
        S1["SendService"]:::backend
        S2["SimpleAuthService"]:::backend
        subgraph "Akka Actor System"
            AC1["Core Actors"]:::backend
            AC2["Cluster Actors"]:::backend
            AC3["Discovery Actors"]:::backend
            AC4["Persistent Actors"]:::backend
            AC5["Router Actors"]:::backend
            AC6["SSE Actors"]:::backend
            AC7["Stateful Actors"]:::backend
            AC8["Stream Actors"]:::backend
            AC9["Supervisor & Timer Actors"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        D1["R2DBC Repositories"]:::database
        subgraph "Durable State Repos"
            R1["DurableRepository"]:::database
            R2["DurableStateDAOImpl"]:::database
        end
        subgraph "DAO/DTO Definitions"
            R3["DAO"]:::database
            R4["DTO"]:::database
        end
    end

    %% Config & Utils
    subgraph "Configuration & Utils"
        CFG1["AkkaConfiguration"]:::backend
        CFG2["WebFluxConfig & OpenAPI"]:::backend
        CFG3["R2dbcPoolConfig"]:::backend
        CFG4["AkkaUtils"]:::backend
    end

    %% External Services
    subgraph "External Services"
        E1["Kafka"]:::external
        E2["RabbitMQ"]:::external
        E3["Redis"]:::external
        E4["Docker Test Env"]:::external
    end

    %% Connections
    C1 -->|"HTTP/SSE/WS"| A1
    C2 -->|"SSE/WS"| A7
    C3 -->|"JSON Contracts"| SM
    SM -->|"DTOs shared"| C1
    SM -->|"DTOs shared"| AC4

    A1 -->|"invoke"| S1
    A2 -->|"invoke"| S1
    A3 -->|"invoke"| S2
    S1 -->|"tell/ask"| AC1
    AC1 -->|"persist events"| R1
    AC4 -->|"snapshot"| R2
    AC1 -->|"project"| R3
    R3 -->|"read model"| A1
    AC6 -->|"SSE events"| C1
    AC6 -->|"WS messages"| C1
    AC7 -->|"state store"| R2

    %% Click Events
    click C1 "https://github.com/psmon/kopring-reactive-labs/tree/main/BlazorWebApp/BlazorFront"
    click C2 "https://github.com/psmon/kopring-reactive-labs/tree/main/BlazorWebApp/BlazorFront/wwwroot/js"
    click C3 "https://github.com/psmon/kopring-reactive-labs/blob/main/BlazorWebApp/BlazorFront/Util/JsonUtil.cs"
    click SM "https://github.com/psmon/kopring-reactive-labs/tree/main/CommonModel/src/main/kotlin/labs/common/model"
    click A0 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/KotlinBootReactiveLabsApplication.kt"
    click A1 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/actor/ActorController.kt"
    click A2 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/actor/cluster/ClusterController.kt"
    click A3 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/auth/AuthController.kt"
    click A4 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/admin"
    click A5 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/dummy/ChatController.kt"
    click A6 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/pubsub/PubSubController.kt"
    click A7 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/controller/sse/SseController.kt"
    click A8 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/ws/ReactiveWebSocketConfig.kt"
    click S1 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/service/SendService.kt"
    click S2 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/service/SimpleAuthService.kt"
    click AC1 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/core"
    click AC2 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/cluster"
    click AC3 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/discovery"
    click AC4 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/persistent/durable"
    click AC5 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/router"
    click AC6 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/sse"
    click AC7 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/state"
    click AC8 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/stream"
    click AC9 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/actor/supervisor"
    click R1 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/repositories/durable/DurableRepository.kt"
    click R2 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/repositories/durable/DurableStateDAOImpl.kt"
    click CFG1 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/config/AkkaConfiguration.kt"
    click CFG2 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/config/WebFluxConfig.kt"
    click CFG3 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/config/R2dbcPoolConfig.kt"
    click CFG4 "https://github.com/psmon/kopring-reactive-labs/blob/main/KotlinBootReactiveLabs/src/main/kotlin/org/example/kotlinbootreactivelabs/module/AkkaUtils.kt"
    click E4 "https://github.com/psmon/kopring-reactive-labs/tree/main/KotlinBootReactiveLabs/src/test/docker"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000
    classDef backend fill:#98FB98,stroke:#000,color:#000
    classDef database fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#D3D3D3,stroke:#000,color:#000
    classDef shared fill:#87CEFA,stroke:#000,color:#000
```
