# hi-polarbear/officialauthentication architecture

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

- Interactive diagram: https://gitdiagram.com/hi-polarbear/officialauthentication
- Repository: https://github.com/hi-polarbear/officialauthentication

## Overview

OfficialAuthentication is a dual-mode Minecraft plugin that lets an online-mode AUTH server bind authenticated UUIDs to current names in MySQL, while an offline-mode MAIN server looks up names and exposes premium/offline identity through PlaceholderAPI and optional name prefixes. The README documents the main write/read workflow, rename history, admin commands, /zb messages, and configurable bind notifications. Sampled source confirms cache-to-repository lookup, repository persistence, PAPI formatting, and prefix behavior; other event and command wiring is inferred only where documented, so uncertain direct call links are omitted.

Main entry points: [`src/main/java/com/mention/officialAuthentication/cache/AuthService.java`](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/cache/AuthService.java) (Lookup service), [`src/main/java/com/mention/officialAuthentication/db/AuthRepository.java`](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/db/AuthRepository.java) (Identity repository), [`src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java`](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java) (Player events), [`src/main/java/com/mention/officialAuthentication/papi/OfficialAuthExpansion.java`](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/papi/OfficialAuthExpansion.java) (PAPI expansion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_binding["Identity binding"]
  node_listener["Player events"]
  node_repo["Identity repository"]
  node_notify["Bind notification"]
end

subgraph group_recognition["Main recognition"]
  node_authservice["Lookup service<br/>[AuthService.java]"]
  node_cache[("TTL cache<br/>[AuthCache.java]")]
  node_result["Auth result<br/>[AuthResult.java]"]
end

subgraph group_presentation["Player presentation"]
  node_expansion["PAPI expansion"]
  node_values["Placeholder formatting"]
  node_prefix["Name prefixes"]
  node_zb["Status messages<br/>[ZbCommand.java]"]
end

subgraph group_operations["Plugin operations"]
  node_plugin["Plugin lifecycle"]
  node_config["Mode config<br/>[AuthConfig.java]"]
  node_database["Database manager"]
  node_commands["Admin commands"]
end

node_player(("Player"))
node_authserver["AUTH server"]
node_mainserver["MAIN server"]
node_mysql[("MySQL")]
node_consumers["PAPI consumers"]

node_player -->|"logs into"| node_authserver
node_authserver -->|"dispatches join"| node_listener
node_listener -->|"binds identity"| node_repo
node_repo -->|"writes identity history"| node_mysql
node_mysql -->|"returns records"| node_repo
node_listener -->|"triggers notice"| node_notify
node_notify -->|"shows bind result"| node_player
node_player -->|"logs into"| node_mainserver
node_mainserver -->|"dispatches login"| node_listener
node_listener -->|"requests lookup"| node_authservice
node_authservice -->|"checks or stores"| node_cache
node_authservice -->|"looks up name"| node_repo
node_repo -->|"reads identity"| node_mysql
node_mysql -->|"returns identity"| node_repo
node_authservice -->|"produces status"| node_result
node_expansion -->|"resolves name"| node_authservice
node_expansion -->|"formats result"| node_values
node_consumers -->|"requests placeholders"| node_expansion
node_prefix -->|"resolves status"| node_authservice
node_prefix -.->|"sets name prefix"| node_consumers
node_zb -->|"checks status"| node_authservice
node_commands -->|"queries or unlinks"| node_repo
node_commands -->|"cleans history"| node_mysql
node_plugin -->|"initializes storage"| node_database
node_plugin -->|"registers expansion"| node_expansion
node_plugin -->|"loads settings"| node_config

click node_plugin "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/OfficialAuthentication.java"
click node_config "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/config/AuthConfig.java"
click node_listener "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java"
click node_repo "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/db/AuthRepository.java"
click node_database "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/db/DatabaseManager.java"
click node_authservice "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/cache/AuthService.java"
click node_cache "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/cache/AuthCache.java"
click node_result "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/model/AuthResult.java"
click node_expansion "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/papi/OfficialAuthExpansion.java"
click node_values "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/util/PlaceholderValues.java"
click node_prefix "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/feature/NamePrefixService.java"
click node_commands "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/command/OfficialAuthCommand.java"
click node_zb "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/command/ZbCommand.java"
click node_notify "https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java"

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_listener,node_repo,node_notify toneBlue
class node_authservice,node_cache,node_result,node_mysql toneAmber
class node_expansion,node_values,node_prefix,node_zb,node_authserver,node_mainserver,node_consumers toneMint
class node_plugin,node_config,node_database,node_commands toneRose
class node_player toneIndigo
```

## Components

### Identity binding

- [Player events](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java): `src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java`
- [Identity repository](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/db/AuthRepository.java): `src/main/java/com/mention/officialAuthentication/db/AuthRepository.java`
- [Bind notification](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java): `src/main/java/com/mention/officialAuthentication/listener/PlayerListener.java`

### Main recognition

- [Lookup service](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/cache/AuthService.java): `src/main/java/com/mention/officialAuthentication/cache/AuthService.java`
- [TTL cache](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/cache/AuthCache.java): `src/main/java/com/mention/officialAuthentication/cache/AuthCache.java`
- [Auth result](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/model/AuthResult.java): `src/main/java/com/mention/officialAuthentication/model/AuthResult.java`

### Player presentation

- [PAPI expansion](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/papi/OfficialAuthExpansion.java): `src/main/java/com/mention/officialAuthentication/papi/OfficialAuthExpansion.java`
- [Placeholder formatting](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/util/PlaceholderValues.java): `src/main/java/com/mention/officialAuthentication/util/PlaceholderValues.java`
- [Name prefixes](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/feature/NamePrefixService.java): `src/main/java/com/mention/officialAuthentication/feature/NamePrefixService.java`
- [Status messages](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/command/ZbCommand.java): `src/main/java/com/mention/officialAuthentication/command/ZbCommand.java`

### Plugin operations

- [Plugin lifecycle](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/OfficialAuthentication.java): `src/main/java/com/mention/officialAuthentication/OfficialAuthentication.java`
- [Mode config](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/config/AuthConfig.java): `src/main/java/com/mention/officialAuthentication/config/AuthConfig.java`
- [Database manager](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/db/DatabaseManager.java): `src/main/java/com/mention/officialAuthentication/db/DatabaseManager.java`
- [Admin commands](https://github.com/hi-polarbear/officialauthentication/blob/main/src/main/java/com/mention/officialAuthentication/command/OfficialAuthCommand.java): `src/main/java/com/mention/officialAuthentication/command/OfficialAuthCommand.java`

### Other components

- **Player**
- **AUTH server**
- **MAIN server**
- **MySQL**
- **PAPI consumers**

## Connections

- Player → AUTH server: logs into
- AUTH server → Player events: dispatches join
- Player events → Identity repository: binds identity
- Identity repository → MySQL: writes identity history
- MySQL → Identity repository: returns records
- Player events → Bind notification: triggers notice
- Bind notification → Player: shows bind result
- Player → MAIN server: logs into
- MAIN server → Player events: dispatches login
- Player events → Lookup service: requests lookup
- Lookup service → TTL cache: checks or stores
- Lookup service → Identity repository: looks up name
- Identity repository → MySQL: reads identity
- MySQL → Identity repository: returns identity
- Lookup service → Auth result: produces status
- PAPI expansion → Lookup service: resolves name
- PAPI expansion → Placeholder formatting: formats result
- PAPI consumers → PAPI expansion: requests placeholders
- Name prefixes → Lookup service: resolves status
- Name prefixes → PAPI consumers: sets name prefix
- Status messages → Lookup service: checks status
- Admin commands → Identity repository: queries or unlinks
- Admin commands → MySQL: cleans history
- Plugin lifecycle → Database manager: initializes storage
- Plugin lifecycle → PAPI expansion: registers expansion
- Plugin lifecycle → Mode config: loads settings