# ikavon/maidllmlocal architecture

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

- Interactive diagram: https://gitdiagram.com/ikavon/maidllmlocal
- Repository: https://github.com/ikavon/maidllmlocal

## Overview

MaidLLMLocal is a Minecraft mod that lets each player’s client handle its own AI requests and credentials, while the server coordinates requests and preserves fallback behavior. The main flow routes LLM chat to either a player’s local compatible endpoint or MAICA; MAICA also provides conversational state, triggers, and optional speech synthesis. README capabilities include per-player configuration, automatic MAICA login, MTrigger actions, and experimental shared memory. Some protocol and integration wiring is unsampled, so the graph omits uncertain links.

Main entry points: [`src/main/java/com/maidllmlocal/relay/RelayHub.java`](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/relay/RelayHub.java) (Server relay), [`src/main/java/com/maidllmlocal/MaidLLMLocal.java`](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/MaidLLMLocal.java) (Mod bootstrap), [`src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java`](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java) (Chat handler), [`src/main/java/com/maidllmlocal/client/ClientRelayHandler.java`](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientRelayHandler.java) (Client relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Mod integration"]
  node_mod["Mod bootstrap<br/>[MaidLLMLocal.java]"]
  node_site_types["Site types"]
  node_mixin["LLM interception"]
  node_packets["Network packages"]
end

subgraph group_maica["MAICA chat"]
  node_maica_client["MAICA client<br/>[MaicaClient.java]"]
  node_maica_session["WebSocket session"]
  node_session_manager["Session manager"]
  node_maica_handler["Chat handler"]
  node_maica_result["Round results"]
  node_triggers["MTrigger actions<br/>[MaicaTrigger.java]"]
end

subgraph group_relay["Player relay"]
  node_relay_site["Relay site<br/>[RelaySite.java]"]
  node_relay_hub["Server relay<br/>[RelayHub.java]"]
  node_relay_handler["Client relay"]
  node_server_mt["Server MTrigger state<br/>[ServerMtState.java]"]
end

subgraph group_voice["Speech and accounts"]
  node_tts_site["MTTS site<br/>[MttsSite.java]"]
  node_tts_client["MTTS client<br/>[MttsClient.java]"]
  node_tts_handler["Client TTS handler"]
  node_account["Account configuration"]
  node_auto_login["Automatic login"]
  node_auth["MAICA authentication"]
end

node_player(("Player"))
node_server(("Minecraft server"))
node_maica_service(("MAICA service"))
node_local_endpoint(("Player LLM endpoint"))

node_mod -->|"registers"| node_packets
node_mod -->|"uses"| node_relay_hub
node_mod -->|"registers"| node_site_types
node_mixin -->|"delegates to"| node_relay_hub
node_relay_site -->|"uses"| node_relay_hub
node_relay_hub -->|"dispatches request"| node_player
node_player -->|"handles request"| node_relay_handler
node_relay_handler -->|"posts HTTP"| node_local_endpoint
node_relay_handler -->|"returns response"| node_server
node_maica_client -->|"routes chat"| node_maica_session
node_maica_handler -->|"gets session"| node_session_manager
node_session_manager -->|"creates session"| node_maica_session
node_maica_handler -->|"returns result"| node_maica_result
node_maica_session -->|"WebSocket chat"| node_maica_service
node_maica_client -->|"applies actions"| node_triggers
node_maica_handler -->|"sends response"| node_packets
node_tts_site -->|"creates client"| node_tts_client
node_tts_handler -->|"requests speech"| node_maica_service
node_auto_login -->|"reads credentials"| node_account
node_auto_login -.->|"authenticates with"| node_auth
node_player -->|"configures"| node_account
node_server -->|"routes chat"| node_player
node_server -->|"requests speech"| node_player
node_maica_service -->|"returns chat"| node_maica_result

click node_mod "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/MaidLLMLocal.java"
click node_site_types "https://github.com/ikavon/maidllmlocal/tree/main/src/main/java/com/maidllmlocal/maica"
click node_mixin "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/mixin/LLMOpenAIClientMixin.java"
click node_packets "https://github.com/ikavon/maidllmlocal/tree/main/src/main/java/com/maidllmlocal/network"
click node_maica_client "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MaicaClient.java"
click node_maica_session "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/maica/MaicaWsSession.java"
click node_session_manager "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/maica/ClientMaicaSessions.java"
click node_maica_handler "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java"
click node_maica_result "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MaicaRoundResult.java"
click node_triggers "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MaicaTrigger.java"
click node_relay_site "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/relay/RelaySite.java"
click node_relay_hub "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/relay/RelayHub.java"
click node_relay_handler "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientRelayHandler.java"
click node_server_mt "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ServerMtState.java"
click node_tts_site "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MttsSite.java"
click node_tts_client "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MttsClient.java"
click node_tts_handler "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientMttsHandler.java"
click node_account "https://github.com/ikavon/maidllmlocal/tree/main/src/main/java/com/maidllmlocal/account"
click node_auto_login "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/maica/MaicaAutoLogin.java"
click node_auth "https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/account/MaicaAuthClient.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_mod,node_site_types,node_mixin,node_packets toneBlue
class node_maica_client,node_maica_session,node_session_manager,node_maica_handler,node_maica_result,node_triggers toneAmber
class node_relay_site,node_relay_hub,node_relay_handler,node_server_mt,node_server toneMint
class node_tts_site,node_tts_client,node_tts_handler,node_account,node_auto_login,node_auth toneRose
class node_player,node_maica_service,node_local_endpoint toneIndigo
```

## Components

### Mod integration

- [Mod bootstrap](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/MaidLLMLocal.java): `src/main/java/com/maidllmlocal/MaidLLMLocal.java`
- [Site types](https://github.com/ikavon/maidllmlocal/tree/main/src/main/java/com/maidllmlocal/maica): `src/main/java/com/maidllmlocal/maica`
- [LLM interception](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/mixin/LLMOpenAIClientMixin.java): `src/main/java/com/maidllmlocal/mixin/LLMOpenAIClientMixin.java`
- [Network packages](https://github.com/ikavon/maidllmlocal/tree/main/src/main/java/com/maidllmlocal/network): `src/main/java/com/maidllmlocal/network`

### MAICA chat

- [MAICA client](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MaicaClient.java): `src/main/java/com/maidllmlocal/maica/MaicaClient.java`
- [WebSocket session](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/maica/MaicaWsSession.java): `src/main/java/com/maidllmlocal/client/maica/MaicaWsSession.java`
- [Session manager](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/maica/ClientMaicaSessions.java): `src/main/java/com/maidllmlocal/client/maica/ClientMaicaSessions.java`
- [Chat handler](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java): `src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java`
- [Round results](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MaicaRoundResult.java): `src/main/java/com/maidllmlocal/maica/MaicaRoundResult.java`
- [MTrigger actions](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MaicaTrigger.java): `src/main/java/com/maidllmlocal/maica/MaicaTrigger.java`

### Player relay

- [Relay site](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/relay/RelaySite.java): `src/main/java/com/maidllmlocal/relay/RelaySite.java`
- [Server relay](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/relay/RelayHub.java): `src/main/java/com/maidllmlocal/relay/RelayHub.java`
- [Client relay](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientRelayHandler.java): `src/main/java/com/maidllmlocal/client/ClientRelayHandler.java`
- [Server MTrigger state](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ServerMtState.java): `src/main/java/com/maidllmlocal/client/ServerMtState.java`

### Speech and accounts

- [MTTS site](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MttsSite.java): `src/main/java/com/maidllmlocal/maica/MttsSite.java`
- [MTTS client](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/maica/MttsClient.java): `src/main/java/com/maidllmlocal/maica/MttsClient.java`
- [Client TTS handler](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/ClientMttsHandler.java): `src/main/java/com/maidllmlocal/client/ClientMttsHandler.java`
- [Account configuration](https://github.com/ikavon/maidllmlocal/tree/main/src/main/java/com/maidllmlocal/account): `src/main/java/com/maidllmlocal/account`
- [Automatic login](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/client/maica/MaicaAutoLogin.java): `src/main/java/com/maidllmlocal/client/maica/MaicaAutoLogin.java`
- [MAICA authentication](https://github.com/ikavon/maidllmlocal/blob/main/src/main/java/com/maidllmlocal/account/MaicaAuthClient.java): `src/main/java/com/maidllmlocal/account/MaicaAuthClient.java`

### Other components

- **Player**
- **Minecraft server**
- **MAICA service**
- **Player LLM endpoint**

## Connections

- Mod bootstrap → Network packages: registers (evidence: `src/main/java/com/maidllmlocal/MaidLLMLocal.java`)
- Mod bootstrap → Server relay: uses (evidence: `src/main/java/com/maidllmlocal/MaidLLMLocal.java`)
- Mod bootstrap → Site types: registers (evidence: `src/main/java/com/maidllmlocal/MaidLLMLocal.java`)
- LLM interception → Server relay: delegates to (evidence: `src/main/java/com/maidllmlocal/mixin/LLMOpenAIClientMixin.java`)
- Relay site → Server relay: uses (evidence: `src/main/java/com/maidllmlocal/relay/RelaySite.java`)
- Server relay → Player: dispatches request (evidence: `src/main/java/com/maidllmlocal/relay/RelayHub.java`)
- Player → Client relay: handles request (evidence: `src/main/java/com/maidllmlocal/client/ClientRelayHandler.java`)
- Client relay → Player LLM endpoint: posts HTTP (evidence: `src/main/java/com/maidllmlocal/client/ClientRelayHandler.java`)
- Client relay → Minecraft server: returns response (evidence: `src/main/java/com/maidllmlocal/client/ClientRelayHandler.java`)
- MAICA client → WebSocket session: routes chat (evidence: `src/main/java/com/maidllmlocal/maica/MaicaClient.java`)
- Chat handler → Session manager: gets session (evidence: `src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java`)
- Session manager → WebSocket session: creates session (evidence: `src/main/java/com/maidllmlocal/client/maica/ClientMaicaSessions.java`)
- Chat handler → Round results: returns result (evidence: `src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java`)
- WebSocket session → MAICA service: WebSocket chat (evidence: `src/main/java/com/maidllmlocal/client/maica/MaicaWsSession.java`)
- MAICA client → MTrigger actions: applies actions (evidence: `src/main/java/com/maidllmlocal/maica/MaicaClient.java`)
- Chat handler → Network packages: sends response (evidence: `src/main/java/com/maidllmlocal/client/ClientMaicaHandler.java`)
- MTTS site → MTTS client: creates client (evidence: `src/main/java/com/maidllmlocal/maica/MttsSite.java`)
- Client TTS handler → MAICA service: requests speech (evidence: `README.md`)
- Automatic login → Account configuration: reads credentials (evidence: `src/main/java/com/maidllmlocal/client/maica/MaicaAutoLogin.java`)
- Automatic login → MAICA authentication: authenticates with (evidence: `src/main/java/com/maidllmlocal/client/maica/MaicaAutoLogin.java`)
- Player → Account configuration: configures (evidence: `README.md`)
- Minecraft server → Player: routes chat (evidence: `README.md`)
- Minecraft server → Player: requests speech (evidence: `README.md`)
- MAICA service → Round results: returns chat