# yassine-jemi01/minecraft-status architecture

> Architecture diagram of the GitHub repository yassine-jemi01/minecraft-status, 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/yassine-jemi01/minecraft-status
- Repository: https://github.com/yassine-jemi01/minecraft-status

## Overview

Minecraft Status is a desktop Python application that reads a local Minecraft Java world and publishes its current state as Discord Rich Presence. Its main runtime loop detects the active world, gathers player, biome, statistics, and advancement data, then updates Discord; separate CLI operations manage configuration, background processes, and optional OS auto-start. The README documents compatibility across legacy and modern world layouts. The graph follows documented behavior and indexed references; unsampled implementation details are not inferred beyond those references.

Main entry points: [`src/minecraft_status/main.py`](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/main.py) (CLI and Runtime), [`src/minecraft_status/minecraft_reader/advancements.py`](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/advancements.py) (Advancement Reader), [`src/minecraft_status/minecraft_reader/biome.py`](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/biome.py) (Biome Reader), [`src/minecraft_status/user_config.py`](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/user_config.py) (User Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Presence"]
  node_main["CLI and Runtime<br/>[main.py]"]
  node_presence["Discord Presence"]
end

subgraph group_world["World Data Readers"]
  node_locator["Active World Locator<br/>[locator.py]"]
  node_player["Player and World Data<br/>[player_data.py]"]
  node_stats["Stats and Playtime<br/>[stats.py]"]
  node_advancements["Advancement Reader<br/>[advancements.py]"]
  node_adv_names["Advancement Titles"]
  node_biome["Biome Reader<br/>[biome.py]"]
  node_legacy_biomes["Legacy Biome IDs<br/>[legacy_biomes.py]"]
  node_world_format["World Format<br/>[world_format.py]"]
end

subgraph group_settings["Configuration and Secrets"]
  node_defaults["Default Settings<br/>[config.py]"]
  node_user_config["User Configuration<br/>[user_config.py]"]
  node_secure_store[("Encrypted Config Store<br/>[secure_store.py]")]
end

subgraph group_operations["Process and Auto-start"]
  node_process["Background Process Manager<br/>[process_manager.py]"]
  node_autostart["Auto-start Manager"]
end

node_user(("User"))
node_discord(("Discord Desktop"))
node_minecraft[("Minecraft Save Files")]
node_os(("Operating System"))

node_user -->|"runs commands"| node_main
node_main -->|"locates world"| node_locator
node_main -->|"reads player"| node_player
node_main -->|"reads stats"| node_stats
node_main -->|"reads advancements"| node_advancements
node_main -->|"reads biome"| node_biome
node_advancements -->|"uses legacy stats"| node_stats
node_advancements -->|"gets player UUID"| node_player
node_advancements -->|"formats titles"| node_adv_names
node_biome -->|"maps legacy IDs"| node_legacy_biomes
node_biome -->|"uses format rules"| node_world_format
node_main -->|"updates presence"| node_presence
node_presence -->|"publishes activity"| node_discord
node_main -->|"loads defaults"| node_defaults
node_main -->|"manages settings"| node_user_config
node_user_config -->|"merges defaults"| node_defaults
node_user_config -->|"loads and saves"| node_secure_store
node_main -->|"controls background"| node_process
node_main -->|"configures auto-start"| node_autostart
node_autostart -->|"checks client ID"| node_user_config
node_process -->|"gets config directory"| node_secure_store
node_autostart -->|"registers startup"| node_os
node_locator -->|"checks session lock"| node_minecraft
node_player -->|"reads world files"| node_minecraft
node_stats -->|"reads stats files"| node_minecraft
node_advancements -->|"reads advancement files"| node_minecraft
node_biome -->|"reads chunk data"| node_minecraft

click node_main "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/main.py"
click node_locator "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/locator.py"
click node_player "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/player_data.py"
click node_stats "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/stats.py"
click node_advancements "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/advancements.py"
click node_adv_names "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/advancement_names.py"
click node_biome "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/biome.py"
click node_legacy_biomes "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/legacy_biomes.py"
click node_world_format "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/world_format.py"
click node_presence "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/discord_presence.py"
click node_defaults "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/config.py"
click node_user_config "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/user_config.py"
click node_secure_store "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/secure_store.py"
click node_process "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/process_manager.py"
click node_autostart "https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/autostart_manager.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_main,node_presence,node_user toneBlue
class node_locator,node_player,node_stats,node_advancements,node_adv_names,node_biome,node_legacy_biomes,node_world_format,node_minecraft toneAmber
class node_defaults,node_user_config,node_secure_store toneMint
class node_process,node_autostart toneRose
class node_discord,node_os toneIndigo
```

## Components

### Runtime and Presence

- [CLI and Runtime](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/main.py): `src/minecraft_status/main.py`
- [Discord Presence](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/discord_presence.py): `src/minecraft_status/minecraft_reader/discord_presence.py`

### World Data Readers

- [Active World Locator](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/locator.py): `src/minecraft_status/minecraft_reader/locator.py`
- [Player and World Data](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/player_data.py): `src/minecraft_status/minecraft_reader/player_data.py`
- [Stats and Playtime](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/stats.py): `src/minecraft_status/minecraft_reader/stats.py`
- [Advancement Reader](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/advancements.py): `src/minecraft_status/minecraft_reader/advancements.py`
- [Advancement Titles](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/advancement_names.py): `src/minecraft_status/minecraft_reader/advancement_names.py`
- [Biome Reader](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/biome.py): `src/minecraft_status/minecraft_reader/biome.py`
- [Legacy Biome IDs](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/legacy_biomes.py): `src/minecraft_status/minecraft_reader/legacy_biomes.py`
- [World Format](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/minecraft_reader/world_format.py): `src/minecraft_status/minecraft_reader/world_format.py`

### Configuration and Secrets

- [Default Settings](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/config.py): `src/minecraft_status/config.py`
- [User Configuration](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/user_config.py): `src/minecraft_status/user_config.py`
- [Encrypted Config Store](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/secure_store.py): `src/minecraft_status/secure_store.py`

### Process and Auto-start

- [Background Process Manager](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/process_manager.py): `src/minecraft_status/process_manager.py`
- [Auto-start Manager](https://github.com/yassine-jemi01/minecraft-status/blob/main/src/minecraft_status/autostart_manager.py): `src/minecraft_status/autostart_manager.py`

### Other components

- **User**
- **Discord Desktop**
- **Minecraft Save Files**
- **Operating System**

## Connections

- User → CLI and Runtime: runs commands (evidence: `README.md`)
- CLI and Runtime → Active World Locator: locates world (evidence: `src/minecraft_status/main.py`)
- CLI and Runtime → Player and World Data: reads player (evidence: `src/minecraft_status/main.py`)
- CLI and Runtime → Stats and Playtime: reads stats (evidence: `src/minecraft_status/main.py`)
- CLI and Runtime → Advancement Reader: reads advancements (evidence: `src/minecraft_status/main.py`)
- CLI and Runtime → Biome Reader: reads biome (evidence: `src/minecraft_status/main.py`)
- Advancement Reader → Stats and Playtime: uses legacy stats (evidence: `src/minecraft_status/minecraft_reader/advancements.py`)
- Advancement Reader → Player and World Data: gets player UUID (evidence: `src/minecraft_status/minecraft_reader/advancements.py`)
- Advancement Reader → Advancement Titles: formats titles (evidence: `src/minecraft_status/minecraft_reader/advancements.py`)
- Biome Reader → Legacy Biome IDs: maps legacy IDs (evidence: `src/minecraft_status/minecraft_reader/biome.py`)
- Biome Reader → World Format: uses format rules (evidence: `src/minecraft_status/minecraft_reader/biome.py`)
- CLI and Runtime → Discord Presence: updates presence (evidence: `README.md`)
- Discord Presence → Discord Desktop: publishes activity (evidence: `README.md`)
- CLI and Runtime → Default Settings: loads defaults (evidence: `src/minecraft_status/main.py`)
- CLI and Runtime → User Configuration: manages settings (evidence: `src/minecraft_status/main.py`)
- User Configuration → Default Settings: merges defaults (evidence: `src/minecraft_status/user_config.py`)
- User Configuration → Encrypted Config Store: loads and saves (evidence: `src/minecraft_status/user_config.py`)
- CLI and Runtime → Background Process Manager: controls background (evidence: `src/minecraft_status/main.py`)
- CLI and Runtime → Auto-start Manager: configures auto-start (evidence: `src/minecraft_status/main.py`)
- Auto-start Manager → User Configuration: checks client ID (evidence: `src/minecraft_status/autostart_manager.py`)
- Background Process Manager → Encrypted Config Store: gets config directory (evidence: `src/minecraft_status/process_manager.py`)
- Auto-start Manager → Operating System: registers startup (evidence: `src/minecraft_status/autostart_manager.py`)
- Active World Locator → Minecraft Save Files: checks session lock (evidence: `README.md`)
- Player and World Data → Minecraft Save Files: reads world files (evidence: `README.md`)
- Stats and Playtime → Minecraft Save Files: reads stats files (evidence: `README.md`)
- Advancement Reader → Minecraft Save Files: reads advancement files (evidence: `README.md`)
- Biome Reader → Minecraft Save Files: reads chunk data (evidence: `README.md`)