# valospectra/spectra-server architecture

> Architecture diagram of the GitHub repository valospectra/spectra-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valospectra/spectra-server
- Repository: https://github.com/valospectra/spectra-server

## Overview

ValoSpectra Server ingests observer-client game events, reconstructs match state, and streams updates for tournament overlays; the README describes frontend updates every 100 ms. The graph also preserves replay, preview, support, and backend/statistics capabilities. Edges are limited to README statements and relationships visible in excerpts or the SOURCE INDEX; some replay and preview wiring is only partially evidenced.

Main entry points: [`src/controller/MatchController.ts`](https://github.com/valospectra/spectra-server/blob/main/src/controller/MatchController.ts) (Match controller), [`src/connector/websocketIncoming.ts`](https://github.com/valospectra/spectra-server/blob/main/src/connector/websocketIncoming.ts) (Incoming WebSocket), [`src/model/Match.ts`](https://github.com/valospectra/spectra-server/blob/main/src/model/Match.ts) (Match state), [`src/connector/databaseConnector.ts`](https://github.com/valospectra/spectra-server/blob/main/src/connector/databaseConnector.ts) (Backend connector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and delivery"]
  node_incoming["Incoming WebSocket"]
  node_controller["Match controller<br/>[MatchController.ts]"]
  node_outgoing["Outgoing WebSocket"]
end

subgraph group_match["Match state"]
  node_match["Match state<br/>[Match.ts]"]
  node_team["Team state<br/>[Team.ts]"]
  node_player["Player state<br/>[Player.ts]"]
  node_tools["Tournament settings<br/>[ToolsData.ts]"]
  node_eventdata["Event data types<br/>[eventData.ts]"]
end

subgraph group_extras["Replay and preview"]
  node_replay["Replay entry<br/>[replay.ts]"]
  node_replayplayer["Replay player<br/>[ReplayPlayer.ts]"]
  node_replayconnector["Replay connector"]
  node_previewhandler["Preview handler<br/>[PreviewHandler.ts]"]
  node_previewmodel["Preview model<br/>[PreviewModel.ts]"]
end

subgraph group_services["Services and utilities"]
  node_translator["Valorant translator"]
  node_database["Backend connector"]
  node_support["Support service<br/>[SupportService.ts]"]
  node_logging["Logging<br/>[Logging.ts]"]
end

node_observer(("Observer client"))
node_frontend(("Overlay frontend"))
node_backend[("Application backend")]
node_stats[("Statistics backend")]

node_observer -->|"sends game data"| node_incoming
node_incoming -->|"routes events"| node_controller
node_controller -->|"updates state"| node_match
node_controller -->|"sends match data"| node_outgoing
node_outgoing -->|"streams game state"| node_frontend
node_match -->|"creates teams"| node_team
node_team -->|"creates players"| node_player
node_player -->|"translates game terms"| node_translator
node_match -->|"initializes settings"| node_tools
node_controller -->|"uses backend operations"| node_database
node_database -->|"sends match requests"| node_backend
node_database -->|"sends statistics requests"| node_stats
node_replay -->|"starts playback"| node_replayplayer
node_replay -->|"creates connection"| node_replayconnector
node_replayplayer -->|"uses connector"| node_replayconnector
node_replayconnector -.->|"connects to ingest"| node_incoming
node_previewhandler -->|"uses preview model"| node_previewmodel
node_controller -->|"logs activity"| node_logging
node_incoming -->|"logs activity"| node_logging

click node_incoming "https://github.com/valospectra/spectra-server/blob/main/src/connector/websocketIncoming.ts"
click node_controller "https://github.com/valospectra/spectra-server/blob/main/src/controller/MatchController.ts"
click node_outgoing "https://github.com/valospectra/spectra-server/blob/main/src/connector/websocketOutgoing.ts"
click node_match "https://github.com/valospectra/spectra-server/blob/main/src/model/Match.ts"
click node_team "https://github.com/valospectra/spectra-server/blob/main/src/model/Team.ts"
click node_player "https://github.com/valospectra/spectra-server/blob/main/src/model/Player.ts"
click node_tools "https://github.com/valospectra/spectra-server/blob/main/src/model/ToolsData.ts"
click node_eventdata "https://github.com/valospectra/spectra-server/blob/main/src/model/eventData.ts"
click node_translator "https://github.com/valospectra/spectra-server/blob/main/src/util/ValorantInternalTranslator.ts"
click node_database "https://github.com/valospectra/spectra-server/blob/main/src/connector/databaseConnector.ts"
click node_support "https://github.com/valospectra/spectra-server/blob/main/src/util/SupportService.ts"
click node_replay "https://github.com/valospectra/spectra-server/blob/main/src/replay/replay.ts"
click node_replayplayer "https://github.com/valospectra/spectra-server/blob/main/src/replay/ReplayPlayer.ts"
click node_replayconnector "https://github.com/valospectra/spectra-server/blob/main/src/replay/ReplayConnectorService.ts"
click node_previewhandler "https://github.com/valospectra/spectra-server/blob/main/src/util/previews/PreviewHandler.ts"
click node_previewmodel "https://github.com/valospectra/spectra-server/blob/main/src/util/previews/PreviewModel.ts"
click node_logging "https://github.com/valospectra/spectra-server/blob/main/src/util/Logging.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_incoming,node_controller,node_outgoing,node_observer,node_frontend toneBlue
class node_match,node_team,node_player,node_tools,node_eventdata,node_backend,node_stats toneAmber
class node_replay,node_replayplayer,node_replayconnector,node_previewhandler,node_previewmodel toneMint
class node_translator,node_database,node_support,node_logging toneRose
```

## Components

### Ingestion and delivery

- [Incoming WebSocket](https://github.com/valospectra/spectra-server/blob/main/src/connector/websocketIncoming.ts): `src/connector/websocketIncoming.ts`
- [Match controller](https://github.com/valospectra/spectra-server/blob/main/src/controller/MatchController.ts): `src/controller/MatchController.ts`
- [Outgoing WebSocket](https://github.com/valospectra/spectra-server/blob/main/src/connector/websocketOutgoing.ts): `src/connector/websocketOutgoing.ts`

### Match state

- [Match state](https://github.com/valospectra/spectra-server/blob/main/src/model/Match.ts): `src/model/Match.ts`
- [Team state](https://github.com/valospectra/spectra-server/blob/main/src/model/Team.ts): `src/model/Team.ts`
- [Player state](https://github.com/valospectra/spectra-server/blob/main/src/model/Player.ts): `src/model/Player.ts`
- [Tournament settings](https://github.com/valospectra/spectra-server/blob/main/src/model/ToolsData.ts): `src/model/ToolsData.ts`
- [Event data types](https://github.com/valospectra/spectra-server/blob/main/src/model/eventData.ts): `src/model/eventData.ts`

### Replay and preview

- [Replay entry](https://github.com/valospectra/spectra-server/blob/main/src/replay/replay.ts): `src/replay/replay.ts`
- [Replay player](https://github.com/valospectra/spectra-server/blob/main/src/replay/ReplayPlayer.ts): `src/replay/ReplayPlayer.ts`
- [Replay connector](https://github.com/valospectra/spectra-server/blob/main/src/replay/ReplayConnectorService.ts): `src/replay/ReplayConnectorService.ts`
- [Preview handler](https://github.com/valospectra/spectra-server/blob/main/src/util/previews/PreviewHandler.ts): `src/util/previews/PreviewHandler.ts`
- [Preview model](https://github.com/valospectra/spectra-server/blob/main/src/util/previews/PreviewModel.ts): `src/util/previews/PreviewModel.ts`

### Services and utilities

- [Valorant translator](https://github.com/valospectra/spectra-server/blob/main/src/util/ValorantInternalTranslator.ts): `src/util/ValorantInternalTranslator.ts`
- [Backend connector](https://github.com/valospectra/spectra-server/blob/main/src/connector/databaseConnector.ts): `src/connector/databaseConnector.ts`
- [Support service](https://github.com/valospectra/spectra-server/blob/main/src/util/SupportService.ts): `src/util/SupportService.ts`
- [Logging](https://github.com/valospectra/spectra-server/blob/main/src/util/Logging.ts): `src/util/Logging.ts`

### Other components

- **Observer client**
- **Overlay frontend**
- **Application backend**
- **Statistics backend**

## Connections

- Observer client → Incoming WebSocket: sends game data (evidence: `README.md`)
- Incoming WebSocket → Match controller: routes events (evidence: `src/connector/websocketIncoming.ts`)
- Match controller → Match state: updates state (evidence: `src/controller/MatchController.ts`)
- Match controller → Outgoing WebSocket: sends match data (evidence: `src/controller/MatchController.ts`)
- Outgoing WebSocket → Overlay frontend: streams game state (evidence: `README.md`)
- Match state → Team state: creates teams (evidence: `src/model/Match.ts`)
- Team state → Player state: creates players (evidence: `src/model/Team.ts`)
- Player state → Valorant translator: translates game terms (evidence: `src/model/Player.ts`)
- Match state → Tournament settings: initializes settings (evidence: `src/model/Match.ts`)
- Match controller → Backend connector: uses backend operations (evidence: `src/controller/MatchController.ts`)
- Backend connector → Application backend: sends match requests (evidence: `src/connector/databaseConnector.ts`)
- Backend connector → Statistics backend: sends statistics requests (evidence: `src/connector/databaseConnector.ts`)
- Replay entry → Replay player: starts playback (evidence: `src/replay/replay.ts`)
- Replay entry → Replay connector: creates connection (evidence: `src/replay/replay.ts`)
- Replay player → Replay connector: uses connector (evidence: `src/replay/ReplayPlayer.ts`)
- Replay connector → Incoming WebSocket: connects to ingest (evidence: `src/replay/ReplayConnectorService.ts`)
- Preview handler → Preview model: uses preview model (evidence: `src/util/previews/PreviewHandler.ts`)
- Match controller → Logging: logs activity (evidence: `src/controller/MatchController.ts`)
- Incoming WebSocket → Logging: logs activity (evidence: `src/connector/websocketIncoming.ts`)
