# theoldzoom/samy architecture

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

- Interactive diagram: https://gitdiagram.com/theoldzoom/samy
- Repository: https://github.com/theoldzoom/samy

## Overview

Samy is a Discord bot for moderation, server management, utilities, social features, and scripted message building. The principal workflow is a Discord interaction routed to a command handler, which performs domain work and responds; the excerpts show the router’s command dispatch and the client’s command loading, but not the complete event-to-router wiring. Database and message-builder paths are included as distinct capabilities. Some subsystem paths and relationships are documented or indexed but not sampled, so uncertain links are omitted.

Main entry points: [`src/interaction/Router.ts`](https://github.com/theoldzoom/samy/blob/master/src/interaction/Router.ts) (Interaction router), [`src/libs/scripting/embed/index.ts`](https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/embed/index.ts) (Embed pipeline), [`src/interaction/commands/fun`](https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/fun) (Family and fun), [`src/utils/moderation.ts`](https://github.com/theoldzoom/samy/blob/master/src/utils/moderation.ts) (Moderation logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_client["Bot client<br/>[Client.ts]"]
  node_command_framework["Command framework<br/>[Command.ts]"]
  node_router["Interaction router<br/>[Router.ts]"]
  node_interaction_wrapper["Interaction wrapper<br/>[Interaction.ts]"]
  node_handler_registry["Component handlers<br/>[Handler.ts]"]
end

subgraph group_moderation["Moderation and server"]
  node_moderation_commands["Moderation commands"]
  node_moderation_logic["Moderation logic<br/>[moderation.ts]"]
  node_moderation_config["Moderation config<br/>[moderation.ts]"]
  node_server_commands["Server commands"]
  node_server_events["Server events"]
end

subgraph group_utility["Utility and social"]
  node_utility_commands["Utility commands"]
  node_social_commands["Family and fun"]
  node_social_logic["Social logic<br/>[family.ts]"]
end

subgraph group_builder["Message builder"]
  node_message_scripting["Message scripting"]
  node_embed_parser["Embed parser<br/>[EmbedParser.ts]"]
  node_cv2_parser["Components V2 parser<br/>[Cv2Parser.ts]"]
  node_embed_pipeline["Embed pipeline<br/>[index.ts]"]
  node_tokenizer["Script tokenizer<br/>[Tokenizer.ts]"]
end

subgraph group_data["Persistence and UI"]
  node_prisma[("Prisma database<br/>[Prisma.ts]")]
  node_ui_components["Discord UI components"]
  node_cards["Rendered info cards"]
end

node_discord(("Discord users"))

node_discord -.->|"sends interactions"| node_router
node_client -->|"loads commands"| node_command_framework
node_router -->|"resolves command"| node_command_framework
node_router -->|"wraps interaction"| node_interaction_wrapper
node_router -->|"dispatches components"| node_handler_registry
node_moderation_commands -->|"uses moderation logic"| node_moderation_logic
node_moderation_config -->|"uses moderation logic"| node_moderation_logic
node_moderation_logic -->|"queries data"| node_prisma
node_social_commands -->|"uses family logic"| node_social_logic
node_social_commands -->|"reads and writes"| node_prisma
node_utility_commands -->|"renders server card"| node_cards
node_social_commands -->|"renders social cards"| node_cards
node_moderation_commands -->|"builds responses"| node_ui_components
node_utility_commands -->|"builds responses"| node_ui_components
node_embed_pipeline -->|"parses scripts"| node_embed_parser
node_embed_pipeline -->|"uses tokenizer"| node_tokenizer
node_embed_pipeline -.->|"renders messages"| node_ui_components
node_cv2_parser -->|"tokenizes source"| node_tokenizer
node_message_scripting -->|"provides embed scripts"| node_embed_pipeline
node_message_scripting -->|"provides Components V2"| node_cv2_parser
node_server_events -->|"loads configuration"| node_prisma

click node_client "https://github.com/theoldzoom/samy/blob/master/src/classes/Client.ts"
click node_command_framework "https://github.com/theoldzoom/samy/blob/master/src/classes/Command.ts"
click node_router "https://github.com/theoldzoom/samy/blob/master/src/interaction/Router.ts"
click node_interaction_wrapper "https://github.com/theoldzoom/samy/blob/master/src/classes/Interaction.ts"
click node_handler_registry "https://github.com/theoldzoom/samy/blob/master/src/interaction/Handler.ts"
click node_moderation_commands "https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/moderation"
click node_moderation_logic "https://github.com/theoldzoom/samy/blob/master/src/utils/moderation.ts"
click node_moderation_config "https://github.com/theoldzoom/samy/blob/master/src/interaction/config/moderation.ts"
click node_server_commands "https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/server"
click node_server_events "https://github.com/theoldzoom/samy/tree/master/src/events"
click node_utility_commands "https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/utility"
click node_social_commands "https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/fun"
click node_social_logic "https://github.com/theoldzoom/samy/blob/master/src/utils/family.ts"
click node_message_scripting "https://github.com/theoldzoom/samy/tree/master/src/libs/scripting"
click node_embed_parser "https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/embed/parser/EmbedParser.ts"
click node_cv2_parser "https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/cv2/parser/Cv2Parser.ts"
click node_embed_pipeline "https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/embed/index.ts"
click node_tokenizer "https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/common/Tokenizer.ts"
click node_prisma "https://github.com/theoldzoom/samy/blob/master/src/libs/Prisma.ts"
click node_ui_components "https://github.com/theoldzoom/samy/tree/master/src/utils/ui/components"
click node_cards "https://github.com/theoldzoom/samy/tree/master/src/utils/ui/cards"

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_client,node_command_framework,node_router,node_interaction_wrapper,node_handler_registry,node_discord toneBlue
class node_moderation_commands,node_moderation_logic,node_moderation_config,node_server_commands,node_server_events toneAmber
class node_utility_commands,node_social_commands,node_social_logic toneMint
class node_message_scripting,node_embed_parser,node_cv2_parser,node_embed_pipeline,node_tokenizer toneRose
class node_prisma,node_ui_components,node_cards toneIndigo
```

## Components

### Bot runtime

- [Bot client](https://github.com/theoldzoom/samy/blob/master/src/classes/Client.ts): `src/classes/Client.ts`
- [Command framework](https://github.com/theoldzoom/samy/blob/master/src/classes/Command.ts): `src/classes/Command.ts`
- [Interaction router](https://github.com/theoldzoom/samy/blob/master/src/interaction/Router.ts): `src/interaction/Router.ts`
- [Interaction wrapper](https://github.com/theoldzoom/samy/blob/master/src/classes/Interaction.ts): `src/classes/Interaction.ts`
- [Component handlers](https://github.com/theoldzoom/samy/blob/master/src/interaction/Handler.ts): `src/interaction/Handler.ts`

### Moderation and server

- [Moderation commands](https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/moderation): `src/interaction/commands/moderation`
- [Moderation logic](https://github.com/theoldzoom/samy/blob/master/src/utils/moderation.ts): `src/utils/moderation.ts`
- [Moderation config](https://github.com/theoldzoom/samy/blob/master/src/interaction/config/moderation.ts): `src/interaction/config/moderation.ts`
- [Server commands](https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/server): `src/interaction/commands/server`
- [Server events](https://github.com/theoldzoom/samy/tree/master/src/events): `src/events`

### Utility and social

- [Utility commands](https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/utility): `src/interaction/commands/utility`
- [Family and fun](https://github.com/theoldzoom/samy/tree/master/src/interaction/commands/fun): `src/interaction/commands/fun`
- [Social logic](https://github.com/theoldzoom/samy/blob/master/src/utils/family.ts): `src/utils/family.ts`

### Message builder

- [Message scripting](https://github.com/theoldzoom/samy/tree/master/src/libs/scripting): `src/libs/scripting`
- [Embed parser](https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/embed/parser/EmbedParser.ts): `src/libs/scripting/embed/parser/EmbedParser.ts`
- [Components V2 parser](https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/cv2/parser/Cv2Parser.ts): `src/libs/scripting/cv2/parser/Cv2Parser.ts`
- [Embed pipeline](https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/embed/index.ts): `src/libs/scripting/embed/index.ts`
- [Script tokenizer](https://github.com/theoldzoom/samy/blob/master/src/libs/scripting/common/Tokenizer.ts): `src/libs/scripting/common/Tokenizer.ts`

### Persistence and UI

- [Prisma database](https://github.com/theoldzoom/samy/blob/master/src/libs/Prisma.ts): `src/libs/Prisma.ts`
- [Discord UI components](https://github.com/theoldzoom/samy/tree/master/src/utils/ui/components): `src/utils/ui/components`
- [Rendered info cards](https://github.com/theoldzoom/samy/tree/master/src/utils/ui/cards): `src/utils/ui/cards`

### Other components

- **Discord users**

## Connections

- Discord users → Interaction router: sends interactions
- Bot client → Command framework: loads commands (evidence: `src/classes/Client.ts`)
- Interaction router → Command framework: resolves command (evidence: `src/interaction/Router.ts`)
- Interaction router → Interaction wrapper: wraps interaction (evidence: `src/interaction/Router.ts`)
- Interaction router → Component handlers: dispatches components (evidence: `src/interaction/Router.ts`)
- Moderation commands → Moderation logic: uses moderation logic (evidence: `src/interaction/commands/moderation/lockdown.ts`)
- Moderation config → Moderation logic: uses moderation logic (evidence: `src/interaction/config/moderation.ts`)
- Moderation logic → Prisma database: queries data (evidence: `src/utils/moderation.ts`)
- Family and fun → Social logic: uses family logic (evidence: `src/interaction/commands/fun/family.ts`)
- Family and fun → Prisma database: reads and writes (evidence: `src/interaction/commands/fun/family.ts`)
- Utility commands → Rendered info cards: renders server card (evidence: `src/interaction/commands/utility/server.ts`)
- Family and fun → Rendered info cards: renders social cards (evidence: `src/interaction/commands/fun/family.ts`)
- Moderation commands → Discord UI components: builds responses (evidence: `src/interaction/commands/moderation/lockdown.ts`)
- Utility commands → Discord UI components: builds responses (evidence: `src/interaction/commands/utility/server.ts`)
- Embed pipeline → Embed parser: parses scripts (evidence: `src/libs/scripting/embed/index.ts`)
- Embed pipeline → Script tokenizer: uses tokenizer (evidence: `src/libs/scripting/embed/index.ts`)
- Embed pipeline → Discord UI components: renders messages
- Components V2 parser → Script tokenizer: tokenizes source (evidence: `src/libs/scripting/cv2/parser/Cv2Parser.ts`)
- Message scripting → Embed pipeline: provides embed scripts (evidence: `src/libs/scripting/embed/index.ts`)
- Message scripting → Components V2 parser: provides Components V2 (evidence: `src/libs/scripting/cv2/parser/Cv2Parser.ts`)
- Server events → Prisma database: loads configuration (evidence: `src/events/forcedNickReady.ts`)
