# kareemmas3ud/fc26-analytics architecture

> Architecture diagram of the GitHub repository kareemmas3ud/fc26-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kareemmas3ud/fc26-analytics
- Repository: https://github.com/kareemmas3ud/fc26-analytics

## Overview

FC 26 Live Match Analytics simulates match telemetry, streams it through Kafka and Spark into Cassandra, and combines live data with historical Wyscout analytics in a Streamlit dashboard. The principal workflow is dashboard match setup → simulator roster lookup and event generation → Kafka → Spark’s raw and windowed streams → Cassandra → dashboard visualization. Separately, CSV ingestion populates ClickHouse dimensions and historical events for roster lookup, name resolution, and historical comparisons. The sampled sources support these connections; the dashboard excerpt is partial, so unsampled details are omitted.

Main entry points: [`app.py`](https://github.com/kareemmas3ud/fc26-analytics/blob/main/app.py) (Live Dashboard), [`simulator.py`](https://github.com/kareemmas3ud/fc26-analytics/blob/main/simulator.py) (Match Simulator), [`streaming_pipeline.py`](https://github.com/kareemmas3ud/fc26-analytics/blob/main/streaming_pipeline.py) (Spark Streaming), [`wyscout_data`](https://github.com/kareemmas3ud/fc26-analytics/tree/main/wyscout_data) (Wyscout CSVs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Live Match"]
  node_config["Match Config<br/>[app.py]"]
  node_simulator["Match Simulator<br/>[simulator.py]"]
end

subgraph group_stream["Stream Processing"]
  node_kafka["Kafka Broker"]
  node_spark["Spark Streaming"]
  node_cassandra[("Cassandra Speed Layer")]
  node_schema_setup["Speed Schema Setup<br/>[setup_cassandra.py]"]
end

subgraph group_batch["Historical Analytics"]
  node_clickhouse[("ClickHouse Analytics")]
  node_csv["Wyscout CSVs"]
  node_event_ingest["Event Ingestion<br/>[batch_ingestion.py]"]
  node_dimension_ingest["Dimension Ingestion"]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Live Dashboard<br/>[app.py]"]
end

node_user(("Operator"))

node_user -->|"configures match"| node_dashboard
node_dashboard -->|"writes setup"| node_config
node_simulator -->|"reads setup"| node_config
node_simulator -->|"looks up rosters"| node_clickhouse
node_simulator -->|"publishes events"| node_kafka
node_kafka -->|"streams events"| node_spark
node_spark -->|"writes raw events"| node_cassandra
node_spark -->|"upserts window stats"| node_cassandra
node_dashboard -->|"queries live data"| node_cassandra
node_dashboard -->|"queries analytics"| node_clickhouse
node_csv -->|"supplies events"| node_event_ingest
node_csv -->|"supplies dimensions"| node_dimension_ingest
node_event_ingest -->|"loads event history"| node_clickhouse
node_dimension_ingest -->|"loads dimensions"| node_clickhouse
node_schema_setup -->|"creates tables"| node_cassandra

click node_dashboard "https://github.com/kareemmas3ud/fc26-analytics/blob/main/app.py"
click node_config "https://github.com/kareemmas3ud/fc26-analytics/blob/main/app.py"
click node_simulator "https://github.com/kareemmas3ud/fc26-analytics/blob/main/simulator.py"
click node_spark "https://github.com/kareemmas3ud/fc26-analytics/blob/main/streaming_pipeline.py"
click node_csv "https://github.com/kareemmas3ud/fc26-analytics/tree/main/wyscout_data"
click node_event_ingest "https://github.com/kareemmas3ud/fc26-analytics/blob/main/batch_ingestion.py"
click node_dimension_ingest "https://github.com/kareemmas3ud/fc26-analytics/blob/main/ingest_dimensions.py"
click node_schema_setup "https://github.com/kareemmas3ud/fc26-analytics/blob/main/setup_cassandra.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_config,node_simulator toneBlue
class node_kafka,node_spark,node_cassandra,node_schema_setup toneAmber
class node_clickhouse,node_csv,node_event_ingest,node_dimension_ingest toneMint
class node_dashboard toneRose
class node_user toneIndigo
```

## Components

### Live Match

- [Match Config](https://github.com/kareemmas3ud/fc26-analytics/blob/main/app.py): `app.py`
- [Match Simulator](https://github.com/kareemmas3ud/fc26-analytics/blob/main/simulator.py): `simulator.py`

### Stream Processing

- **Kafka Broker**
- [Spark Streaming](https://github.com/kareemmas3ud/fc26-analytics/blob/main/streaming_pipeline.py): `streaming_pipeline.py`
- **Cassandra Speed Layer**
- [Speed Schema Setup](https://github.com/kareemmas3ud/fc26-analytics/blob/main/setup_cassandra.py): `setup_cassandra.py`

### Historical Analytics

- **ClickHouse Analytics**
- [Wyscout CSVs](https://github.com/kareemmas3ud/fc26-analytics/tree/main/wyscout_data): `wyscout_data`
- [Event Ingestion](https://github.com/kareemmas3ud/fc26-analytics/blob/main/batch_ingestion.py): `batch_ingestion.py`
- [Dimension Ingestion](https://github.com/kareemmas3ud/fc26-analytics/blob/main/ingest_dimensions.py): `ingest_dimensions.py`

### Dashboard

- [Live Dashboard](https://github.com/kareemmas3ud/fc26-analytics/blob/main/app.py): `app.py`

### Other components

- **Operator**

## Connections

- Operator → Live Dashboard: configures match
- Live Dashboard → Match Config: writes setup
- Match Simulator → Match Config: reads setup
- Match Simulator → ClickHouse Analytics: looks up rosters
- Match Simulator → Kafka Broker: publishes events
- Kafka Broker → Spark Streaming: streams events
- Spark Streaming → Cassandra Speed Layer: writes raw events
- Spark Streaming → Cassandra Speed Layer: upserts window stats
- Live Dashboard → Cassandra Speed Layer: queries live data
- Live Dashboard → ClickHouse Analytics: queries analytics
- Wyscout CSVs → Event Ingestion: supplies events
- Wyscout CSVs → Dimension Ingestion: supplies dimensions
- Event Ingestion → ClickHouse Analytics: loads event history
- Dimension Ingestion → ClickHouse Analytics: loads dimensions
- Speed Schema Setup → Cassandra Speed Layer: creates tables