# bekmurodgofurov/gsh architecture

> Architecture diagram of the GitHub repository bekmurodgofurov/gsh, 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/bekmurodgofurov/gsh
- Repository: https://github.com/bekmurodgofurov/gsh

## Overview

GSH monitors registered CS2 servers, persists telemetry, classifies anomalies, and presents operational views and controls through a dashboard, AI agent, voice interface, and Telegram alerts. The principal flow is A2S polling → TimescaleDB → ML analysis/incidents → gateway APIs → dashboard or notifications. The README documents several service-to-service links not visible in the sampled excerpts; those links are cited to the README. Internal implementation detail is limited to the gateway agent’s router, tools, and query layer.

Main entry points: [`gateway-api/main.py`](https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/main.py) (Gateway API), [`client/src/components/views`](https://github.com/bekmurodgofurov/gsh/tree/developer/client/src/components/views) (Dashboard views), [`ingestion-service/main.py`](https://github.com/bekmurodgofurov/gsh/blob/developer/ingestion-service/main.py) (Ingestion API), [`anomaly-detection-ml/bridge.py`](https://github.com/bekmurodgofurov/gsh/blob/developer/anomaly-detection-ml/bridge.py) (Anomaly bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection &amp; storage"]
  node_ingestion["A2S ingestion<br/>[poller.py]"]
  node_ingestion_api["Ingestion API<br/>[main.py]"]
  node_schemas["Shared schemas<br/>[models.py]"]
  node_timescale[("TimescaleDB")]
  node_redis["Redis stream"]
end

subgraph group_analysis["ML analysis"]
  node_bridge["Anomaly bridge<br/>[bridge.py]"]
  node_anomaly["Anomaly scoring<br/>[main.py]"]
  node_rootcause["Root-cause classifier<br/>[main.py]"]
end

subgraph group_gateway["Gateway &amp; agent"]
  node_gateway["Gateway API<br/>[main.py]"]
  node_agent_router["Agent router<br/>[router.py]"]
  node_agent_tools["Agent tools<br/>[tools.py]"]
  node_queries["SQL query layer<br/>[queries.py]"]
end

subgraph group_experience["Dashboard &amp; voice"]
  node_dashboard["Dashboard views"]
  node_dashboard_widgets["Dashboard widgets"]
  node_admin["Admin console"]
  node_client_data["Client data hook<br/>[useServerData.js]"]
  node_client_api["Client API<br/>[api.js]"]
  node_ask_panel["Typed agent panel<br/>[AskPanel.jsx]"]
  node_voice["Voice agent<br/>[worker.py]"]
end

subgraph group_alerts["Alerts &amp; reports"]
  node_alerting["Alerting service<br/>[scheduler.py]"]
  node_bot_handlers["Telegram commands<br/>[handlers.py]"]
end

node_servers(("Game servers"))
node_gemini{{"Gemini API"}}
node_livekit{{"LiveKit"}}
node_telegram(("Telegram"))

node_servers -->|"A2S queries"| node_ingestion
node_ingestion -->|"writes metrics"| node_timescale
node_ingestion -->|"publishes metrics"| node_redis
node_ingestion_api -->|"starts polling"| node_ingestion
node_ingestion_api -->|"persists polls"| node_timescale
node_ingestion_api -->|"accepts payloads"| node_schemas
node_timescale -->|"provides telemetry"| node_bridge
node_bridge -->|"requests scoring"| node_anomaly
node_bridge -->|"requests classification"| node_rootcause
node_bridge -->|"saves incidents"| node_timescale
node_timescale -->|"serves dashboard data"| node_gateway
node_gateway -->|"forwards polls"| node_ingestion_api
node_gateway -->|"forwards probes"| node_ingestion_api
node_gateway -->|"registers routes"| node_agent_router
node_agent_router -->|"dispatches tools"| node_agent_tools
node_agent_tools -->|"uses SQL"| node_queries
node_agent_router -->|"requests answers"| node_gemini
node_gateway -->|"serves HTTP and WS"| node_dashboard
node_dashboard -->|"renders views"| node_dashboard_widgets
node_dashboard -->|"routes admin view"| node_admin
node_dashboard -->|"loads fleet state"| node_client_data
node_client_data -->|"fetches data"| node_client_api
node_client_api -->|"calls API"| node_gateway
node_ask_panel -->|"sends questions"| node_client_api
node_timescale -->|"provides events"| node_alerting
node_alerting -->|"sends alerts"| node_telegram
node_alerting -->|"sends reports"| node_telegram
node_bot_handlers -->|"reads and updates"| node_timescale
node_bot_handlers -->|"replies to commands"| node_telegram
node_dashboard -->|"exchanges audio"| node_livekit
node_livekit -->|"routes session"| node_voice
node_voice -->|"calls agent tools"| node_gateway
node_voice -->|"uses realtime model"| node_gemini

click node_ingestion "https://github.com/bekmurodgofurov/gsh/blob/developer/ingestion-service/poller.py"
click node_ingestion_api "https://github.com/bekmurodgofurov/gsh/blob/developer/ingestion-service/main.py"
click node_schemas "https://github.com/bekmurodgofurov/gsh/blob/developer/shared_schemas/models.py"
click node_bridge "https://github.com/bekmurodgofurov/gsh/blob/developer/anomaly-detection-ml/bridge.py"
click node_anomaly "https://github.com/bekmurodgofurov/gsh/blob/developer/anomaly-detection-ml/main.py"
click node_rootcause "https://github.com/bekmurodgofurov/gsh/blob/developer/root-cause-ml/main.py"
click node_gateway "https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/main.py"
click node_agent_router "https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/app/agent/router.py"
click node_agent_tools "https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/app/agent/tools.py"
click node_queries "https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/queries.py"
click node_dashboard "https://github.com/bekmurodgofurov/gsh/tree/developer/client/src/components/views"
click node_dashboard_widgets "https://github.com/bekmurodgofurov/gsh/tree/developer/client/src/components/dashboard"
click node_admin "https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/components/views/AdminDashboardView.jsx"
click node_client_data "https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/hooks/useServerData.js"
click node_client_api "https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/services/api.js"
click node_ask_panel "https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/components/common/AskPanel.jsx"
click node_voice "https://github.com/bekmurodgofurov/gsh/blob/developer/voice-agent/worker.py"
click node_alerting "https://github.com/bekmurodgofurov/gsh/blob/developer/alerting-service/scheduler.py"
click node_bot_handlers "https://github.com/bekmurodgofurov/gsh/blob/developer/alerting-service/handlers.py"

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_ingestion,node_ingestion_api,node_schemas,node_timescale,node_redis toneBlue
class node_bridge,node_anomaly,node_rootcause toneAmber
class node_gateway,node_agent_router,node_agent_tools,node_queries,node_servers,node_gemini toneMint
class node_dashboard,node_dashboard_widgets,node_admin,node_client_data,node_client_api,node_ask_panel,node_voice toneRose
class node_alerting,node_bot_handlers,node_livekit,node_telegram toneIndigo
```

## Components

### Collection & storage

- [A2S ingestion](https://github.com/bekmurodgofurov/gsh/blob/developer/ingestion-service/poller.py): `ingestion-service/poller.py`
- [Ingestion API](https://github.com/bekmurodgofurov/gsh/blob/developer/ingestion-service/main.py): `ingestion-service/main.py`
- [Shared schemas](https://github.com/bekmurodgofurov/gsh/blob/developer/shared_schemas/models.py): `shared_schemas/models.py`
- **TimescaleDB**
- **Redis stream**

### ML analysis

- [Anomaly bridge](https://github.com/bekmurodgofurov/gsh/blob/developer/anomaly-detection-ml/bridge.py): `anomaly-detection-ml/bridge.py`
- [Anomaly scoring](https://github.com/bekmurodgofurov/gsh/blob/developer/anomaly-detection-ml/main.py): `anomaly-detection-ml/main.py`
- [Root-cause classifier](https://github.com/bekmurodgofurov/gsh/blob/developer/root-cause-ml/main.py): `root-cause-ml/main.py`

### Gateway & agent

- [Gateway API](https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/main.py): `gateway-api/main.py`
- [Agent router](https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/app/agent/router.py): `gateway-api/app/agent/router.py`
- [Agent tools](https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/app/agent/tools.py): `gateway-api/app/agent/tools.py`
- [SQL query layer](https://github.com/bekmurodgofurov/gsh/blob/developer/gateway-api/queries.py): `gateway-api/queries.py`

### Dashboard & voice

- [Dashboard views](https://github.com/bekmurodgofurov/gsh/tree/developer/client/src/components/views): `client/src/components/views`
- [Dashboard widgets](https://github.com/bekmurodgofurov/gsh/tree/developer/client/src/components/dashboard): `client/src/components/dashboard`
- [Admin console](https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/components/views/AdminDashboardView.jsx): `client/src/components/views/AdminDashboardView.jsx`
- [Client data hook](https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/hooks/useServerData.js): `client/src/hooks/useServerData.js`
- [Client API](https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/services/api.js): `client/src/services/api.js`
- [Typed agent panel](https://github.com/bekmurodgofurov/gsh/blob/developer/client/src/components/common/AskPanel.jsx): `client/src/components/common/AskPanel.jsx`
- [Voice agent](https://github.com/bekmurodgofurov/gsh/blob/developer/voice-agent/worker.py): `voice-agent/worker.py`

### Alerts & reports

- [Alerting service](https://github.com/bekmurodgofurov/gsh/blob/developer/alerting-service/scheduler.py): `alerting-service/scheduler.py`
- [Telegram commands](https://github.com/bekmurodgofurov/gsh/blob/developer/alerting-service/handlers.py): `alerting-service/handlers.py`

### Other components

- **Game servers**
- **Gemini API**
- **LiveKit**
- **Telegram**

## Connections

- Game servers → A2S ingestion: A2S queries (evidence: `README.md`)
- A2S ingestion → TimescaleDB: writes metrics (evidence: `README.md`)
- A2S ingestion → Redis stream: publishes metrics (evidence: `README.md`)
- Ingestion API → A2S ingestion: starts polling (evidence: `ingestion-service/main.py`)
- Ingestion API → TimescaleDB: persists polls (evidence: `ingestion-service/main.py`)
- Ingestion API → Shared schemas: accepts payloads (evidence: `ingestion-service/main.py`)
- TimescaleDB → Anomaly bridge: provides telemetry (evidence: `README.md`)
- Anomaly bridge → Anomaly scoring: requests scoring (evidence: `README.md`)
- Anomaly bridge → Root-cause classifier: requests classification (evidence: `README.md`)
- Anomaly bridge → TimescaleDB: saves incidents (evidence: `README.md`)
- TimescaleDB → Gateway API: serves dashboard data (evidence: `README.md`)
- Gateway API → Ingestion API: forwards polls (evidence: `README.md`)
- Gateway API → Ingestion API: forwards probes (evidence: `README.md`)
- Gateway API → Agent router: registers routes (evidence: `gateway-api/main.py`)
- Agent router → Agent tools: dispatches tools (evidence: `gateway-api/app/agent/router.py`)
- Agent tools → SQL query layer: uses SQL (evidence: `gateway-api/app/agent/tools.py`)
- Agent router → Gemini API: requests answers (evidence: `README.md`)
- Gateway API → Dashboard views: serves HTTP and WS (evidence: `README.md`)
- Dashboard views → Dashboard widgets: renders views (evidence: `client/src/components/views/OverviewView.jsx`)
- Dashboard views → Admin console: routes admin view (evidence: `client/src/components/views/AdminWrapper.jsx`)
- Dashboard views → Client data hook: loads fleet state (evidence: `client/src/App.jsx`)
- Client data hook → Client API: fetches data (evidence: `client/src/hooks/useServerData.js`)
- Client API → Gateway API: calls API (evidence: `README.md`)
- Typed agent panel → Client API: sends questions (evidence: `client/src/components/common/AskPanel.jsx`)
- TimescaleDB → Alerting service: provides events (evidence: `README.md`)
- Alerting service → Telegram: sends alerts (evidence: `README.md`)
- Alerting service → Telegram: sends reports (evidence: `alerting-service/scheduler.py`)
- Telegram commands → TimescaleDB: reads and updates (evidence: `alerting-service/handlers.py`)
- Telegram commands → Telegram: replies to commands (evidence: `alerting-service/handlers.py`)
- Dashboard views → LiveKit: exchanges audio (evidence: `README.md`)
- LiveKit → Voice agent: routes session (evidence: `README.md`)
- Voice agent → Gateway API: calls agent tools (evidence: `README.md`)
- Voice agent → Gemini API: uses realtime model (evidence: `README.md`)
