# enderchx/dsms-go architecture

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

- Interactive diagram: https://gitdiagram.com/enderchx/dsms-go
- Repository: https://github.com/enderchx/dsms-go

## Overview

##### Project type and purpose
- This is a Go-based, distributed simulation communication system implementing a publish-subscribe protocol (“DSTP”).
- It provides multiple executables (CLI tools, a simulation broker, GUI client, web client) that interact over network sockets using Protobuf-encoded messages.

##### File structure
- **cmd/** contains five entry points:
- client (generic client CLI)
- server (generic server CLI)
- simulation_center (the pub-sub broker)
- simulation_client (simulation engine client)
- test (test harness)
- **internal/** holds core packages:
- app (desktop GUI via Fyne & web GUI via Gin + static HTML)
- auth (login logic, issues JWTs)
- dstp (connection, framing for the DSTP protocol)
- message_hub (in-memory pub-sub broker logic used by simulation_center)
- protobuf (message definitions, compiled Go stubs)
- simulation (simulation logic for both center and client)
- **utils/** has cross-cutting concerns: JWT handling, logging (Gin middleware & generic logger)

##### README
- Confirms the goal: “Design and implementation of a distributed simulation communication protocol based on publish-subscribe.”

##### Main components
a. **Simulation Center (Broker)**
- Runs cmd/simulation_center
- Hosts message_hub, simulation_center logic, dstp listener
- Accepts connections from all clients, manages topics, forwards messages
b. **Simulation Clients**
- cmd/simulation_client runs simulation_client logic
- Publishes simulation data to center, subscribes to topics for control or aggregated data
c. **Generic Client & Server CLIs**
- cmd/client and cmd/server wrap the same pub-sub mechanism for manual or scripted interactions
d. **UI Clients**
- **Fyne desktop app** (internal/app/fyne_app.go)
- **Gin-backed web app** (internal/app/gin_app.go + static HTML/JS)
- Both connect over DSTP to the center, authenticate via auth/login → JWT
e. **Authentication Service**
- internal/auth/login.go issues JWTs for clients; used by UI and CLI to obtain credentials
f. **Protocol Layer**
- internal/dstp/conn.go handles TCP framing, multiplexing, heartbeats
- internal/protobuf defines message schema (data.proto → data.pb.go)
g. **Utilities**
- JWT utils (utils/jwt/jwt.go)
- Logging (utils/log)

##### Relationships & data flows
- **Clients (Simulation, UI, CLI)** → authenticate via Auth service → receive JWT
- Clients establish DSTP connection over TCP to Simulation Center
- Simulation Clients publish “simulation data” topics → Message Hub within Center
- Other clients subscribe to topics → Hub pushes data → Clients process/display
- Simulation Center may run simulation coordination logic (internal/simulation/simulation_center.go)
- A test harness (cmd/test) can simulate multiple clients or test message flows

##### Architectural patterns & design principles
- **Publish–Subscribe**: decouples producers/consumers via topics, central hub
- **Layered architecture**:
- Protocol layer (dstp)
- Messaging layer (message_hub)
- Business logic (simulation, auth)
- Presentation/CLI layer (app, cmd)
- **Modularization**: everything in `internal/`, clear separation of concerns
- **Technology choices**: Go modules, Protobuf for messages, Fyne for desktop GUI, Gin for web GUI, JWT for auth

##### Final checklist
- Clear, descriptive labels on all nodes (components)
- Annotations for protocols, message formats, ports

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef clients fill:#D6E9FF,stroke:#333,stroke-width:1px
    classDef server fill:#DFF2BF,stroke:#333,stroke-width:1px
    classDef services fill:#F0F0F0,stroke:#333,stroke-width:1px

    subgraph "Clients"
        SC["Simulation Client"]:::clients
        CLIClient["Generic CLI Client"]:::clients
        CLIServer["Generic CLI Server"]:::clients
        Fyne["Fyne Desktop UI"]:::clients
        Gin["Gin Web UI"]:::clients
        TestHarness["Test Harness"]:::clients
    end

    Auth["Auth Service"]:::services
    DSTP["DSTP Protocol\n(internal/dstp)"]:::services
    Protobuf["Protobuf Messages"]:::services
    JWT["JWT Utils"]:::services
    Logging["Logging"]:::services
    messageHub["Message Hub"]:::services
    SimLogic["Simulation Logic"]:::services

    Center["Simulation Center / Broker"]:::server

    %% Authentication flows
    SC -->|HTTP Login| Auth
    CLIClient -->|HTTP Login| Auth
    CLIServer -->|HTTP Login| Auth
    Fyne -->|HTTP Login| Auth
    Gin -->|HTTP Login| Auth
    TestHarness -->|HTTP Login| Auth

    %% DSTP connections
    SC -->|DSTP/TCP| Center
    CLIClient -->|DSTP/TCP| Center
    CLIServer -->|DSTP/TCP| Center
    Fyne -->|DSTP/TCP| Center
    Gin -->|DSTP/TCP| Center
    TestHarness -->|DSTP/TCP| Center

    %% Center uses services
    Center --> messageHub
    messageHub --> Protobuf
    SC --> Protobuf
    Center --> SimLogic
    SC --> SimLogic

    %% Protocol & utilities usage
    SC --> DSTP
    Center --> DSTP
    CLIClient --> DSTP
    CLIServer --> DSTP
    Fyne --> DSTP
    Gin --> DSTP
    TestHarness --> DSTP

    Auth --> JWT
    SC --> JWT
    CLIClient --> JWT
    CLIServer --> JWT
    Fyne --> JWT
    Gin --> JWT
    TestHarness --> JWT

    SC --> Logging
    Center --> Logging
    CLIClient --> Logging
    CLIServer --> Logging
    Fyne --> Logging
    Gin --> Logging
    TestHarness --> Logging

    %% Click Events
    click Center "https://github.com/enderchx/dsms-go/blob/main/cmd/simulation_center/main.go"
    click messageHub "https://github.com/enderchx/dsms-go/blob/main/internal/message_hub/hub.go"
    click SimLogic "https://github.com/enderchx/dsms-go/blob/main/internal/simulation/simulation.go"
    click SC "https://github.com/enderchx/dsms-go/blob/main/cmd/simulation_client/main.go"
    click CLIClient "https://github.com/enderchx/dsms-go/blob/main/cmd/client/main.go"
    click CLIServer "https://github.com/enderchx/dsms-go/blob/main/cmd/server/main.go"
    click Fyne "https://github.com/enderchx/dsms-go/blob/main/internal/app/fyne_app.go"
    click Gin "https://github.com/enderchx/dsms-go/blob/main/internal/app/gin_app.go"
    click Auth "https://github.com/enderchx/dsms-go/blob/main/internal/auth/login.go"
    click DSTP "https://github.com/enderchx/dsms-go/blob/main/internal/dstp/conn.go"
    click Protobuf "https://github.com/enderchx/dsms-go/blob/main/internal/protobuf/data.pb.go"
    click JWT "https://github.com/enderchx/dsms-go/blob/main/utils/jwt/jwt.go"
    click Logging "https://github.com/enderchx/dsms-go/blob/main/utils/log/log.go"
    click TestHarness "https://github.com/enderchx/dsms-go/blob/main/cmd/test/main.go"
```
