# siebrum/minecraft-server-discovery architecture

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

- Interactive diagram: https://gitdiagram.com/siebrum/minecraft-server-discovery
- Repository: https://github.com/siebrum/minecraft-server-discovery

## Overview

The product discovers public Minecraft servers, enriches reachable servers with status and location data, stores them, and presents the results in an Angular website. Its main workflow is manually started IP-range scanning, submission of open hosts to the API, server probing and persistence, then browsing or refreshing records in the website. The README documents these capabilities; some implementation relationships below rely on its statements and the SOURCE INDEX because the corresponding source was not excerpted.

Main entry points: [`backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs) (Discovery API), [`backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs`](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs) (Database context), [`backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs`](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs) (Data conversion), [`backend/MasscanWrapper/Program.cs`](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MasscanWrapper/Program.cs) (Range scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Server discovery"]
  node_scanner["Range scanner<br/>[Program.cs]"]
  node_ip_ranges["IP ranges<br/>[IpRanges.cs]"]
end

subgraph group_api["API and enrichment"]
  node_api_service["Discovery API<br/>[MainController.cs]"]
  node_status_probe["Status probe<br/>[MainController.cs]"]
  node_conversion["Data conversion<br/>[Converters.cs]"]
  node_geo_lookup["Geo enrichment"]
  node_geo_dto["Geo response DTO"]
  node_server_model["Server model<br/>[Server.cs]"]
  node_geo_model["Geo model<br/>[GeoInformation.cs]"]
  node_player_model["Player model<br/>[Player.cs]"]
  node_database_context["Database context<br/>[DatabaseContext.cs]"]
end

subgraph group_web["Website"]
  node_web_root["Angular application<br/>[app.component.ts]"]
  node_home_page["Server listing"]
  node_sidebar["Side menu"]
  node_api_client["API client<br/>[api.service.ts]"]
  node_server_contract["Server contract<br/>[server.model.ts]"]
  node_api_config["API configuration<br/>[environment.ts]"]
end

node_operator(("Operator"))
node_minecraft(("Minecraft servers"))
node_mysql[("MySQL database")]
node_maps(("Google Maps"))

node_operator -->|"starts manually"| node_scanner
node_scanner -->|"uses ranges"| node_ip_ranges
node_scanner -->|"scans hosts"| node_minecraft
node_scanner -->|"submits open hosts"| node_api_service
node_api_service -->|"probes server"| node_status_probe
node_status_probe -->|"queries status"| node_minecraft
node_api_service -->|"converts status"| node_conversion
node_api_service -->|"requests location"| node_geo_lookup
node_geo_lookup -->|"converts location"| node_conversion
node_conversion -->|"maps fields"| node_geo_dto
node_conversion -->|"creates records"| node_server_model
node_conversion -->|"creates records"| node_geo_model
node_api_service -->|"reads and writes"| node_database_context
node_database_context -->|"persists"| node_server_model
node_database_context -->|"persists"| node_geo_model
node_database_context -->|"persists"| node_player_model
node_database_context -->|"connects to"| node_mysql
node_web_root -->|"hosts"| node_home_page
node_web_root -->|"hosts"| node_sidebar
node_home_page -->|"loads and refreshes"| node_api_client
node_api_client -->|"uses URL"| node_api_config
node_home_page -->|"opens location"| node_maps
node_api_client -->|"requests records"| node_api_service
node_api_client -->|"uses response type"| node_server_contract

click node_scanner "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MasscanWrapper/Program.cs"
click node_ip_ranges "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MasscanWrapper/IpRanges.cs"
click node_api_service "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs"
click node_status_probe "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs"
click node_conversion "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs"
click node_geo_lookup "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Helpers/GeoLocationHelper.cs"
click node_geo_dto "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/DTO/ExternalGeoLocationInformation.cs"
click node_server_model "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Models/Server.cs"
click node_geo_model "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Models/GeoInformation.cs"
click node_player_model "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Models/Player.cs"
click node_database_context "https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs"
click node_web_root "https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/app.component.ts"
click node_home_page "https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/app-home-page/app-home-page.component.ts"
click node_sidebar "https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/app-side-menu-bar/app-side-menu-bar.component.ts"
click node_api_client "https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/api.service.ts"
click node_server_contract "https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/models/server.model.ts"
click node_api_config "https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/environments/environment.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_scanner,node_ip_ranges toneBlue
class node_api_service,node_status_probe,node_conversion,node_geo_lookup,node_geo_dto,node_server_model,node_geo_model,node_player_model,node_database_context,node_mysql toneAmber
class node_web_root,node_home_page,node_sidebar,node_api_client,node_server_contract,node_api_config,node_minecraft toneMint
class node_operator,node_maps toneIndigo
```

## Components

### Server discovery

- [Range scanner](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MasscanWrapper/Program.cs): `backend/MasscanWrapper/Program.cs`
- [IP ranges](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MasscanWrapper/IpRanges.cs): `backend/MasscanWrapper/IpRanges.cs`

### API and enrichment

- [Discovery API](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs): `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`
- [Status probe](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs): `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`
- [Data conversion](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs): `backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs`
- [Geo enrichment](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Helpers/GeoLocationHelper.cs): `backend/MinecraftServerDiscoveryApi/Helpers/GeoLocationHelper.cs`
- [Geo response DTO](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/DTO/ExternalGeoLocationInformation.cs): `backend/MinecraftServerDiscoveryApi/DTO/ExternalGeoLocationInformation.cs`
- [Server model](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Models/Server.cs): `backend/MinecraftServerDiscoveryApi/Models/Server.cs`
- [Geo model](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Models/GeoInformation.cs): `backend/MinecraftServerDiscoveryApi/Models/GeoInformation.cs`
- [Player model](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Models/Player.cs): `backend/MinecraftServerDiscoveryApi/Models/Player.cs`
- [Database context](https://github.com/siebrum/minecraft-server-discovery/blob/main/backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs): `backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs`

### Website

- [Angular application](https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/app.component.ts): `website/src/app/app.component.ts`
- [Server listing](https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/app-home-page/app-home-page.component.ts): `website/src/app/app-home-page/app-home-page.component.ts`
- [Side menu](https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/app-side-menu-bar/app-side-menu-bar.component.ts): `website/src/app/app-side-menu-bar/app-side-menu-bar.component.ts`
- [API client](https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/api.service.ts): `website/src/app/api.service.ts`
- [Server contract](https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/app/models/server.model.ts): `website/src/app/models/server.model.ts`
- [API configuration](https://github.com/siebrum/minecraft-server-discovery/blob/main/website/src/environments/environment.ts): `website/src/environments/environment.ts`

### Other components

- **Operator**
- **Minecraft servers**
- **MySQL database**
- **Google Maps**

## Connections

- Operator → Range scanner: starts manually (evidence: `README.md`)
- Range scanner → IP ranges: uses ranges (evidence: `backend/MasscanWrapper/Program.cs`)
- Range scanner → Minecraft servers: scans hosts (evidence: `README.md`)
- Range scanner → Discovery API: submits open hosts (evidence: `README.md`)
- Discovery API → Status probe: probes server (evidence: `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`)
- Status probe → Minecraft servers: queries status (evidence: `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`)
- Discovery API → Data conversion: converts status (evidence: `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`)
- Discovery API → Geo enrichment: requests location (evidence: `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`)
- Geo enrichment → Data conversion: converts location (evidence: `backend/MinecraftServerDiscoveryApi/Helpers/GeoLocationHelper.cs`)
- Data conversion → Geo response DTO: maps fields (evidence: `backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs`)
- Data conversion → Server model: creates records (evidence: `backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs`)
- Data conversion → Geo model: creates records (evidence: `backend/MinecraftServerDiscoveryApi/Helpers/Converters.cs`)
- Discovery API → Database context: reads and writes (evidence: `backend/MinecraftServerDiscoveryApi/Controllers/MainController.cs`)
- Database context → Server model: persists (evidence: `backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs`)
- Database context → Geo model: persists (evidence: `backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs`)
- Database context → Player model: persists (evidence: `backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs`)
- Database context → MySQL database: connects to (evidence: `backend/MinecraftServerDiscoveryApi/Contexts/DatabaseContext.cs`)
- Angular application → Server listing: hosts (evidence: `website/src/app/app.module.ts`)
- Angular application → Side menu: hosts (evidence: `website/src/app/app.module.ts`)
- Server listing → API client: loads and refreshes (evidence: `website/src/app/app-home-page/app-home-page.component.ts`)
- API client → API configuration: uses URL (evidence: `website/src/app/api.service.ts`)
- Server listing → Google Maps: opens location (evidence: `website/src/app/app-home-page/app-home-page.component.ts`)
- API client → Discovery API: requests records (evidence: `README.md`)
- API client → Server contract: uses response type (evidence: `website/src/app/api.service.ts`)
