# tyler-zig/gronk architecture

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

- Interactive diagram: https://gitdiagram.com/tyler-zig/gronk
- Repository: https://github.com/tyler-zig/gronk

## Overview

Gronk is a Discord assistant whose main workflow starts with a mention, reply, or thread message, routes the request, gathers relevant context and attachments, calls Grok, then responds in Discord and retains conversation metadata. Separate workflows provide image generation, Discord-history analysis, channel personas, and verbosity controls. The excerpts show core orchestration and several module responsibilities; some feature wiring is supported by the README but not visible in the sampled source, so uncertain call edges are omitted.

Main entry points: [`main.py`](https://github.com/tyler-zig/gronk/blob/main/main.py) (Bot entry and routing), [`grok_responder.py`](https://github.com/tyler-zig/gronk/blob/main/grok_responder.py) (Grok response handling), [`discord_history.py`](https://github.com/tyler-zig/gronk/blob/main/discord_history.py) (History search and analysis), [`reply_context.py`](https://github.com/tyler-zig/gronk/blob/main/reply_context.py) (Reply and thread context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Discord interaction"]
  node_main["Bot entry and routing<br/>[main.py]"]
  node_reply_context["Reply and thread context<br/>[reply_context.py]"]
  node_media["Media collection<br/>[media_utils.py]"]
  node_discord_history["History search and analysis<br/>[discord_history.py]"]
  node_nlp["Natural-language routing<br/>[nlp_utils.py]"]
end

subgraph group_ai["Grok capabilities"]
  node_responder["Grok response handling<br/>[grok_responder.py]"]
  node_grok_client["Grok chat client<br/>[grok_client.py]"]
  node_document_utils["Document processing<br/>[document_utils.py]"]
  node_schemas["Structured response schemas<br/>[grok_schemas.py]"]
  node_image_generation["Image generation"]
  node_cost["Usage cost estimates<br/>[cost_utils.py]"]
end

subgraph group_personalization["Channel personalization"]
  node_personas["Persona management<br/>[persona_manager.py]"]
  node_verbosity["Response verbosity<br/>[verbosity.py]"]
end

subgraph group_state["Conversation state"]
  node_conversation_store["Conversation records"]
  node_conversation_db[("Conversation database")]
  node_persona_store[("Persona and channel settings")]
end

node_user(("Discord user"))
node_discord["Discord platform"]
node_xai["xAI API and tools"]

node_user -->|"sends message"| node_discord
node_discord -->|"delivers event"| node_main
node_main -->|"reads message"| node_discord
node_main -->|"detects intent"| node_nlp
node_main -->|"gathers context"| node_reply_context
node_reply_context -->|"fetches history"| node_discord
node_reply_context -->|"collects media"| node_media
node_main -->|"collects attachments"| node_media
node_main -->|"dispatches image request"| node_image_generation
node_image_generation -->|"requests images"| node_xai
node_main -->|"dispatches query"| node_responder
node_responder -->|"uploads documents"| node_document_utils
node_responder -->|"requests chat response"| node_grok_client
node_grok_client -->|"calls chat API"| node_xai
node_responder -->|"loads active persona"| node_personas
node_responder -->|"loads style modifier"| node_verbosity
node_verbosity -->|"reads and updates settings"| node_personas
node_personas -->|"reads and writes"| node_persona_store
node_responder -->|"estimates usage cost"| node_cost
node_responder -->|"stores response metadata"| node_conversation_store
node_main -->|"looks up reply context"| node_conversation_store
node_conversation_store -->|"reads and writes"| node_conversation_db
node_responder -->|"sends response"| node_discord
node_main -.->|"routes history requests"| node_discord_history
node_discord_history -->|"scans messages"| node_discord
node_discord_history -.->|"analyzes collected history"| node_grok_client
node_discord_history -->|"sends cited analysis"| node_discord

click node_main "https://github.com/tyler-zig/gronk/blob/main/main.py"
click node_reply_context "https://github.com/tyler-zig/gronk/blob/main/reply_context.py"
click node_media "https://github.com/tyler-zig/gronk/blob/main/media_utils.py"
click node_discord_history "https://github.com/tyler-zig/gronk/blob/main/discord_history.py"
click node_responder "https://github.com/tyler-zig/gronk/blob/main/grok_responder.py"
click node_grok_client "https://github.com/tyler-zig/gronk/blob/main/grok_client.py"
click node_document_utils "https://github.com/tyler-zig/gronk/blob/main/document_utils.py"
click node_schemas "https://github.com/tyler-zig/gronk/blob/main/grok_schemas.py"
click node_image_generation "https://github.com/tyler-zig/gronk/blob/main/image_generation.py"
click node_personas "https://github.com/tyler-zig/gronk/blob/main/persona_manager.py"
click node_verbosity "https://github.com/tyler-zig/gronk/blob/main/verbosity.py"
click node_nlp "https://github.com/tyler-zig/gronk/blob/main/nlp_utils.py"
click node_conversation_store "https://github.com/tyler-zig/gronk/blob/main/conversation_store.py"
click node_conversation_db "https://github.com/tyler-zig/gronk/tree/main/data"
click node_persona_store "https://github.com/tyler-zig/gronk/tree/main/data"
click node_cost "https://github.com/tyler-zig/gronk/blob/main/cost_utils.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_reply_context,node_media,node_discord_history,node_nlp,node_user toneBlue
class node_responder,node_grok_client,node_document_utils,node_schemas,node_image_generation,node_cost toneAmber
class node_personas,node_verbosity,node_xai toneMint
class node_conversation_store,node_conversation_db,node_persona_store toneRose
class node_discord toneIndigo
```

## Components

### Discord interaction

- [Bot entry and routing](https://github.com/tyler-zig/gronk/blob/main/main.py): `main.py`
- [Reply and thread context](https://github.com/tyler-zig/gronk/blob/main/reply_context.py): `reply_context.py`
- [Media collection](https://github.com/tyler-zig/gronk/blob/main/media_utils.py): `media_utils.py`
- [History search and analysis](https://github.com/tyler-zig/gronk/blob/main/discord_history.py): `discord_history.py`
- [Natural-language routing](https://github.com/tyler-zig/gronk/blob/main/nlp_utils.py): `nlp_utils.py`

### Grok capabilities

- [Grok response handling](https://github.com/tyler-zig/gronk/blob/main/grok_responder.py): `grok_responder.py`
- [Grok chat client](https://github.com/tyler-zig/gronk/blob/main/grok_client.py): `grok_client.py`
- [Document processing](https://github.com/tyler-zig/gronk/blob/main/document_utils.py): `document_utils.py`
- [Structured response schemas](https://github.com/tyler-zig/gronk/blob/main/grok_schemas.py): `grok_schemas.py`
- [Image generation](https://github.com/tyler-zig/gronk/blob/main/image_generation.py): `image_generation.py`
- [Usage cost estimates](https://github.com/tyler-zig/gronk/blob/main/cost_utils.py): `cost_utils.py`

### Channel personalization

- [Persona management](https://github.com/tyler-zig/gronk/blob/main/persona_manager.py): `persona_manager.py`
- [Response verbosity](https://github.com/tyler-zig/gronk/blob/main/verbosity.py): `verbosity.py`

### Conversation state

- [Conversation records](https://github.com/tyler-zig/gronk/blob/main/conversation_store.py): `conversation_store.py`
- [Conversation database](https://github.com/tyler-zig/gronk/tree/main/data): `data`
- [Persona and channel settings](https://github.com/tyler-zig/gronk/tree/main/data): `data`

### Other components

- **Discord user**
- **Discord platform**
- **xAI API and tools**

## Connections

- Discord user → Discord platform: sends message
- Discord platform → Bot entry and routing: delivers event
- Bot entry and routing → Discord platform: reads message
- Bot entry and routing → Natural-language routing: detects intent
- Bot entry and routing → Reply and thread context: gathers context
- Reply and thread context → Discord platform: fetches history
- Reply and thread context → Media collection: collects media
- Bot entry and routing → Media collection: collects attachments
- Bot entry and routing → Image generation: dispatches image request
- Image generation → xAI API and tools: requests images
- Bot entry and routing → Grok response handling: dispatches query
- Grok response handling → Document processing: uploads documents
- Grok response handling → Grok chat client: requests chat response
- Grok chat client → xAI API and tools: calls chat API
- Grok response handling → Persona management: loads active persona
- Grok response handling → Response verbosity: loads style modifier
- Response verbosity → Persona management: reads and updates settings
- Persona management → Persona and channel settings: reads and writes
- Grok response handling → Usage cost estimates: estimates usage cost
- Grok response handling → Conversation records: stores response metadata
- Bot entry and routing → Conversation records: looks up reply context
- Conversation records → Conversation database: reads and writes
- Grok response handling → Discord platform: sends response
- Bot entry and routing → History search and analysis: routes history requests
- History search and analysis → Discord platform: scans messages
- History search and analysis → Grok chat client: analyzes collected history
- History search and analysis → Discord platform: sends cited analysis