# navosx/byte architecture

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

- Interactive diagram: https://gitdiagram.com/navosx/byte
- Repository: https://github.com/navosx/byte

## Overview

Byte is a Discord server bot. Its main workflow is Discord events routed by the handler into message, slash-command, and member-join features: messages earn XP and may invoke Gemini chat; commands inspect levels or change color roles; joins receive roles and a welcome embed. Level data is stored in MongoDB and used for rank display and color eligibility. The graph preserves the README’s advertised media-chat and help capabilities. Edges reflect shown calls or README-described behavior; unsampled integrations are not inferred beyond those documented.

Main entry points: [`src/handler.js`](https://github.com/navosx/byte/blob/main/src/handler.js) (Event Handler), [`src/events/commands/changeColor.js`](https://github.com/navosx/byte/blob/main/src/events/commands/changeColor.js) (Color Command), [`src/models/levelSchema.js`](https://github.com/navosx/byte/blob/main/src/models/levelSchema.js) (Level Record Model), [`src/events/messages/main.js`](https://github.com/navosx/byte/blob/main/src/events/messages/main.js) (Message Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Discord Runtime"]
  node_entry["Bot Startup<br/>[main.js]"]
  node_ready["Ready Event<br/>[ready.js]"]
  node_handler["Event Handler<br/>[handler.js]"]
  node_message_router["Message Router<br/>[main.js]"]
  node_command_router["Command Router<br/>[main.js]"]
end

subgraph group_community["Community Features"]
  node_welcome["Welcome Flow<br/>[welcome.js]"]
  node_color["Color Command<br/>[changeColor.js]"]
  node_add_role["Add Role<br/>[addRole.js]"]
  node_remove_role["Remove Role<br/>[removeRole.js]"]
end

subgraph group_levels["Leveling"]
  node_xp["XP Awarding<br/>[giveXp.js]"]
  node_level_command["Rank Inspection<br/>[inspectLevel.js]"]
  node_level_math["Level XP Formula"]
  node_level_fetch["Level Fetch<br/>[fetchDB.js]"]
  node_level_model["Level Record Model<br/>[levelSchema.js]"]
end

subgraph group_ai["AI Chat"]
  node_chat["Gemini Chat<br/>[main.js]"]
end

subgraph group_integrations["External Services"]
  node_discord{{"Discord Gateway"}}
  node_mongo[("MongoDB")]
  node_gemini{{"Gemini API"}}
end

node_member(("Server Member"))

node_member -->|"sends events"| node_discord
node_discord -->|"delivers events"| node_handler
node_entry -->|"starts"| node_ready
node_ready -->|"registers handlers"| node_handler
node_handler -->|"routes messages"| node_message_router
node_handler -->|"routes commands"| node_command_router
node_handler -->|"routes joins"| node_welcome
node_message_router -->|"awards XP"| node_xp
node_message_router -->|"invokes on mention"| node_chat
node_command_router -->|"dispatches color"| node_color
node_command_router -->|"dispatches level"| node_level_command
node_welcome -->|"assigns roles"| node_add_role
node_color -->|"checks eligibility"| node_level_fetch
node_color -->|"removes old color"| node_remove_role
node_color -->|"assigns selected color"| node_add_role
node_xp -->|"checks threshold"| node_level_math
node_level_command -->|"calculates XP"| node_level_math
node_xp -->|"reads and saves"| node_level_model
node_level_command -->|"queries records"| node_level_model
node_level_fetch -->|"queries records"| node_level_model
node_level_model -->|"persists level data"| node_mongo
node_chat -->|"generates responses"| node_gemini
node_chat -->|"replies with text or media"| node_member

click node_entry "https://github.com/navosx/byte/blob/main/src/main.js"
click node_ready "https://github.com/navosx/byte/blob/main/src/events/ready.js"
click node_handler "https://github.com/navosx/byte/blob/main/src/handler.js"
click node_message_router "https://github.com/navosx/byte/blob/main/src/events/messages/main.js"
click node_command_router "https://github.com/navosx/byte/blob/main/src/events/commands/main.js"
click node_welcome "https://github.com/navosx/byte/blob/main/src/events/welcome.js"
click node_color "https://github.com/navosx/byte/blob/main/src/events/commands/changeColor.js"
click node_add_role "https://github.com/navosx/byte/blob/main/src/utils/addRole.js"
click node_remove_role "https://github.com/navosx/byte/blob/main/src/utils/removeRole.js"
click node_xp "https://github.com/navosx/byte/blob/main/src/events/messages/giveXp.js"
click node_level_command "https://github.com/navosx/byte/blob/main/src/events/commands/inspectLevel.js"
click node_level_math "https://github.com/navosx/byte/blob/main/src/utils/calculateLevelXp.js"
click node_level_fetch "https://github.com/navosx/byte/blob/main/src/utils/fetchDB.js"
click node_level_model "https://github.com/navosx/byte/blob/main/src/models/levelSchema.js"
click node_chat "https://github.com/navosx/byte/blob/main/src/gemini/chat/main.js"

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_entry,node_ready,node_handler,node_message_router,node_command_router toneBlue
class node_welcome,node_color,node_add_role,node_remove_role toneAmber
class node_xp,node_level_command,node_level_math,node_level_fetch,node_level_model,node_member toneMint
class node_chat toneRose
class node_discord,node_mongo,node_gemini toneIndigo
```

## Components

### Discord Runtime

- [Bot Startup](https://github.com/navosx/byte/blob/main/src/main.js): `src/main.js`
- [Ready Event](https://github.com/navosx/byte/blob/main/src/events/ready.js): `src/events/ready.js`
- [Event Handler](https://github.com/navosx/byte/blob/main/src/handler.js): `src/handler.js`
- [Message Router](https://github.com/navosx/byte/blob/main/src/events/messages/main.js): `src/events/messages/main.js`
- [Command Router](https://github.com/navosx/byte/blob/main/src/events/commands/main.js): `src/events/commands/main.js`

### Community Features

- [Welcome Flow](https://github.com/navosx/byte/blob/main/src/events/welcome.js): `src/events/welcome.js`
- [Color Command](https://github.com/navosx/byte/blob/main/src/events/commands/changeColor.js): `src/events/commands/changeColor.js`
- [Add Role](https://github.com/navosx/byte/blob/main/src/utils/addRole.js): `src/utils/addRole.js`
- [Remove Role](https://github.com/navosx/byte/blob/main/src/utils/removeRole.js): `src/utils/removeRole.js`

### Leveling

- [XP Awarding](https://github.com/navosx/byte/blob/main/src/events/messages/giveXp.js): `src/events/messages/giveXp.js`
- [Rank Inspection](https://github.com/navosx/byte/blob/main/src/events/commands/inspectLevel.js): `src/events/commands/inspectLevel.js`
- [Level XP Formula](https://github.com/navosx/byte/blob/main/src/utils/calculateLevelXp.js): `src/utils/calculateLevelXp.js`
- [Level Fetch](https://github.com/navosx/byte/blob/main/src/utils/fetchDB.js): `src/utils/fetchDB.js`
- [Level Record Model](https://github.com/navosx/byte/blob/main/src/models/levelSchema.js): `src/models/levelSchema.js`

### AI Chat

- [Gemini Chat](https://github.com/navosx/byte/blob/main/src/gemini/chat/main.js): `src/gemini/chat/main.js`

### External Services

- **Discord Gateway**
- **MongoDB**
- **Gemini API**

### Other components

- **Server Member**

## Connections

- Server Member → Discord Gateway: sends events (evidence: `README.md`)
- Discord Gateway → Event Handler: delivers events (evidence: `src/handler.js`)
- Bot Startup → Ready Event: starts (evidence: `src/main.js`)
- Ready Event → Event Handler: registers handlers (evidence: `src/events/ready.js`)
- Event Handler → Message Router: routes messages (evidence: `src/handler.js`)
- Event Handler → Command Router: routes commands (evidence: `src/handler.js`)
- Event Handler → Welcome Flow: routes joins (evidence: `src/handler.js`)
- Message Router → XP Awarding: awards XP (evidence: `src/events/messages/main.js`)
- Message Router → Gemini Chat: invokes on mention (evidence: `src/events/messages/main.js`)
- Command Router → Color Command: dispatches color (evidence: `src/events/commands/main.js`)
- Command Router → Rank Inspection: dispatches level (evidence: `src/events/commands/main.js`)
- Welcome Flow → Add Role: assigns roles (evidence: `src/events/welcome.js`)
- Color Command → Level Fetch: checks eligibility (evidence: `src/events/commands/changeColor.js`)
- Color Command → Remove Role: removes old color (evidence: `src/events/commands/changeColor.js`)
- Color Command → Add Role: assigns selected color (evidence: `src/events/commands/changeColor.js`)
- XP Awarding → Level XP Formula: checks threshold (evidence: `src/events/messages/giveXp.js`)
- Rank Inspection → Level XP Formula: calculates XP (evidence: `src/events/commands/inspectLevel.js`)
- XP Awarding → Level Record Model: reads and saves (evidence: `src/events/messages/giveXp.js`)
- Rank Inspection → Level Record Model: queries records (evidence: `src/events/commands/inspectLevel.js`)
- Level Fetch → Level Record Model: queries records (evidence: `src/utils/fetchDB.js`)
- Level Record Model → MongoDB: persists level data (evidence: `README.md`)
- Gemini Chat → Gemini API: generates responses (evidence: `src/gemini/chat/main.js`)
- Gemini Chat → Server Member: replies with text or media (evidence: `src/gemini/chat/main.js`)
