# gitginocchio/flarecord-rs architecture

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

- Interactive diagram: https://gitdiagram.com/gitginocchio/flarecord-rs
- Repository: https://github.com/gitginocchio/flarecord-rs

## Overview

1. **What this repo is**
   - Flarecord is a Rust library for building **Discord interaction bots** on **Cloudflare Workers**.
   - The architecture is intentionally **stateless and webhook-driven**: it handles slash commands and other interactions rather than running a Discord Gateway client.

2. **Runtime and deployment boundary**
   - The framework targets **WASM/WebAssembly** and the Cloudflare Workers runtime.
   - That constraint shapes the architecture: lightweight request handling, async execution, no long-lived gateway connection, and interaction-first workflows.

3. **Public API layer**
   - `src/lib.rs` and `src/prelude.rs` are the main export surfaces for application authors.
   - Consumers build bots and implement commands/components through the framework’s traits and builders rather than wiring internals directly.

4. **Bot orchestration subsystem**
   - `src/bot/` contains the bot-level configuration and coordination logic.
   - `builder.rs` suggests a builder-style setup for bot initialization, while `state.rs` holds runtime state needed during request processing and command sync.

5. **Interaction pipeline**
   - The core data flow starts with Discord sending an interaction payload to the Worker.
   - That payload is represented through `src/models/interaction.rs` and then specialized into feature-specific pipelines under `command`, `autocomplete`, `components`, and `modals`.
   - Each interaction family has its own `context`, `data`, `dispatcher`, and `interaction` modules, showing a clean separation between parsing, dispatch, and execution context.

6. **Commands as the primary feature**
   - `src/models/command/` is the largest subsystem and is the main extension point.
   - It contains command metadata, options, dispatching, interaction wrappers, and response builders.
   - Subcommand support is modeled explicitly in the examples, indicating the framework supports nested command hierarchies, not just flat slash commands.

7. **Response construction**
   - Command execution returns structured response types under `src/models/command/response/`.
   - This is where the framework turns command logic into Discord-compatible replies, including ephemeral and deferred-style responses described in the README.
   - The response builder layer keeps application code separate from Discord payload formatting.

8. **Other interaction families**
   - `src/models/autocomplete/` handles autocomplete suggestion flows.
   - `src/models/components/` is organized around message components, with separate folders for **interactive** elements like buttons/selects and **layout/content** elements like containers, sections, separators, files, thumbnails, and media galleries.
   - `src/models/modals/` isolates modal submission handling.
   - This suggests each interaction type has an independent dispatch path but shares the same bot/runtime boundary.

9. **Discord domain model layer**
   - Supporting types live under `src/models/`: attachments, embeds, users, colors, and command options/values.
   - These types form the schema layer between Discord’s API shapes and the framework’s higher-level abstractions.
   - `serializable.rs` indicates some models are designed to be converted back into API payloads.

10. **Trait-based extensibility**
   - `src/traits/` defines the abstraction boundary for application-defined behavior.
   - `component.rs` and `resolvable.rs` imply the framework uses traits for pluggable dispatch and for resolving Discord entities or option values into typed Rust data.
   - This is the main point where user code plugs into the framework.

11. **Discord service boundary**
   - `src/services/discord.rs` is the external API integration layer.
   - Its responsibility is likely Discord REST interactions such as command synchronization and sending/verifying interaction-related requests, keeping network concerns out of the command/model layers.

12. **Security and request validation**
   - `src/crypto.rs` is a distinct infrastructure boundary, likely used for Discord signature verification.
   - That separation is important in a Workers setting because every incoming interaction request must be authenticated before dispatching to command logic.

13. **Error handling**
   - `src/error.rs` centralizes framework errors, which the README and docs frame as comprehensive and type-safe.
   - This keeps parsing, dispatch, service calls, and user command failures in a single error model.

14. **Examples and documentation as architecture guides**
   - The `examples/` directory shows how the framework is composed in practice: simple bots, command-heavy bots, component-based bots, and nested subcommand trees.
   - The `docs/` folder is organized by subsystem (`COMMANDS`, `OPTIONS`, `RESPONSES`, `INTERACTIONS`, `BOT`, `WASM`, etc.), closely matching the code structure and reinforcing the framework’s modular boundaries.

15. **Overall data flow to diagram**
   - The clearest architectural path is: **Discord interaction request → crypto verification → bot state/context creation → interaction dispatcher → feature-specific handler (command/autocomplete/component/modal) → response builder → Discord response/API call**.
   - The main boundaries to show are: **external Discord API**, **Workers/WASM runtime**, **framework core**, and **application-defined commands/components**.

Main entry points: [`src/models/command/mod.rs`](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/mod.rs) (Commands), [`src/bot/mod.rs`](https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/mod.rs) (Bot Core), [`src/models/interaction.rs`](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/interaction.rs) (Interaction Base), [`src/lib.rs`](https://github.com/gitginocchio/flarecord-rs/blob/main/src/lib.rs) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime Boundary"]
end

subgraph group_grp_core["Framework Core"]
  node_n_lib["Public API<br/>crate exports<br/>[lib.rs]"]
  node_n_prelude["Prelude<br/>exports<br/>[prelude.rs]"]
  node_n_bot["Bot Core<br/>orchestration<br/>[mod.rs]"]
  node_n_bot_builder["Bot Builder<br/>setup<br/>[builder.rs]"]
  node_n_bot_state["Bot State<br/>runtime state<br/>[state.rs]"]
  node_n_crypto{{"Request Crypto<br/>verification<br/>[crypto.rs]"}}
  node_n_error["Error Model<br/>errors<br/>[error.rs]"]
  node_n_service["Discord Service<br/>rest integration<br/>[discord.rs]"]
end

subgraph group_grp_models["Interaction Models"]
  node_n_interaction["Interaction Base<br/>payload model<br/>[interaction.rs]"]
  node_n_command["Commands<br/>slash command pipeline<br/>[mod.rs]"]
  node_n_command_dispatcher["Command Dispatch<br/>[dispatcher.rs]"]
  node_n_command_response["Command Responses<br/>response building<br/>[mod.rs]"]
  node_n_autocomplete["Autocomplete<br/>interaction pipeline<br/>[mod.rs]"]
  node_n_components["Components<br/>interaction pipeline<br/>[mod.rs]"]
  node_n_modals["Modals<br/>interaction pipeline<br/>[mod.rs]"]
  node_n_domain["Discord Models<br/>schema types<br/>[mod.rs]"]
end

subgraph group_grp_ext["Extensibility"]
  node_n_traits["Framework Traits<br/>abstractions<br/>[mod.rs]"]
end

subgraph group_grp_examples["Examples"]
  node_n_examples_simple["Simple Bot<br/>example app<br/>[lib.rs]"]
  node_n_examples_commands["Command Bot<br/>example app<br/>[lib.rs]"]
  node_n_examples_subcommands["Subcommands<br/>example app<br/>[lib.rs]"]
  node_n_examples_components["Components Demo<br/>example app<br/>[lib.rs]"]
end

node_n_lib -->|"re-exports"| node_n_prelude
node_n_lib -->|"builds on"| node_n_bot
node_n_lib -->|"exposes"| node_n_interaction
node_n_bot -->|"configured by"| node_n_bot_builder
node_n_bot -->|"holds"| node_n_bot_state
node_n_bot -->|"verifies"| node_n_crypto
node_n_bot -->|"syncs via"| node_n_service
node_n_bot -->|"reports"| node_n_error
node_n_interaction -->|"specializes to"| node_n_command
node_n_interaction -->|"specializes to"| node_n_autocomplete
node_n_interaction -->|"specializes to"| node_n_components
node_n_interaction -->|"specializes to"| node_n_modals
node_n_command -->|"dispatches through"| node_n_command_dispatcher
node_n_command -->|"returns"| node_n_command_response
node_n_command -->|"uses"| node_n_traits
node_n_autocomplete -->|"uses"| node_n_traits
node_n_components -->|"uses"| node_n_traits
node_n_modals -->|"uses"| node_n_traits
node_n_command -->|"reads"| node_n_domain
node_n_components -->|"uses"| node_n_domain
node_n_domain -->|"serializes for"| node_n_service
node_n_service -->|"returns"| node_n_error
node_n_crypto -->|"returns"| node_n_error
node_n_examples_simple -->|"uses"| node_n_lib
node_n_examples_commands -->|"uses"| node_n_lib
node_n_examples_subcommands -->|"demonstrates"| node_n_command
node_n_examples_components -->|"demonstrates"| node_n_components
node_n_examples_commands -->|"demonstrates"| node_n_components
node_n_examples_commands -->|"demonstrates"| node_n_command

click node_n_lib "https://github.com/gitginocchio/flarecord-rs/blob/main/src/lib.rs"
click node_n_prelude "https://github.com/gitginocchio/flarecord-rs/blob/main/src/prelude.rs"
click node_n_bot "https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/mod.rs"
click node_n_bot_builder "https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/builder.rs"
click node_n_bot_state "https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/state.rs"
click node_n_crypto "https://github.com/gitginocchio/flarecord-rs/blob/main/src/crypto.rs"
click node_n_error "https://github.com/gitginocchio/flarecord-rs/blob/main/src/error.rs"
click node_n_service "https://github.com/gitginocchio/flarecord-rs/blob/main/src/services/discord.rs"
click node_n_interaction "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/interaction.rs"
click node_n_command "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/mod.rs"
click node_n_command_dispatcher "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/dispatcher.rs"
click node_n_command_response "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/response/mod.rs"
click node_n_autocomplete "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/autocomplete/mod.rs"
click node_n_components "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/components/mod.rs"
click node_n_modals "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/modals/mod.rs"
click node_n_domain "https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/mod.rs"
click node_n_traits "https://github.com/gitginocchio/flarecord-rs/blob/main/src/traits/mod.rs"
click node_n_examples_simple "https://github.com/gitginocchio/flarecord-rs/blob/main/examples/simple/src/lib.rs"
click node_n_examples_commands "https://github.com/gitginocchio/flarecord-rs/blob/main/examples/with_commands/src/lib.rs"
click node_n_examples_subcommands "https://github.com/gitginocchio/flarecord-rs/blob/main/examples/subcommands/src/lib.rs"
click node_n_examples_components "https://github.com/gitginocchio/flarecord-rs/blob/main/examples/components/src/lib.rs"

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_n_lib,node_n_prelude,node_n_bot,node_n_bot_builder,node_n_bot_state,node_n_crypto,node_n_error,node_n_service toneAmber
class node_n_interaction,node_n_command,node_n_command_dispatcher,node_n_command_response,node_n_autocomplete,node_n_components,node_n_modals,node_n_domain toneMint
class node_n_traits toneRose
class node_n_examples_simple,node_n_examples_commands,node_n_examples_subcommands,node_n_examples_components toneIndigo
```

## Components

### Framework Core

Public API, bot orchestration, security, errors, and Discord service integration.

- [Public API](https://github.com/gitginocchio/flarecord-rs/blob/main/src/lib.rs): crate exports · Main library surface for application authors. · `src/lib.rs`
- [Prelude](https://github.com/gitginocchio/flarecord-rs/blob/main/src/prelude.rs): exports · Convenient re-export surface for common framework types. · `src/prelude.rs`
- [Bot Core](https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/mod.rs): orchestration · Bot construction, configuration, and runtime coordination. · `src/bot/mod.rs`
- [Bot Builder](https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/builder.rs): setup · Builder-style initialization for bot configuration. · `src/bot/builder.rs`
- [Bot State](https://github.com/gitginocchio/flarecord-rs/blob/main/src/bot/state.rs): runtime state · State carried through request handling and sync flows. · `src/bot/state.rs`
- [Request Crypto](https://github.com/gitginocchio/flarecord-rs/blob/main/src/crypto.rs): verification · Signature and request authentication boundary. · `src/crypto.rs`
- [Error Model](https://github.com/gitginocchio/flarecord-rs/blob/main/src/error.rs): errors · Central framework error types. · `src/error.rs`
- [Discord Service](https://github.com/gitginocchio/flarecord-rs/blob/main/src/services/discord.rs): rest integration · External Discord API integration and synchronization calls. · `src/services/discord.rs`

### Interaction Models

Shared interaction pipeline and Discord domain schemas.

- [Interaction Base](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/interaction.rs): payload model · Shared interaction envelope from Discord. · `src/models/interaction.rs`
- [Commands](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/mod.rs): slash command pipeline · Primary command subsystem for parsing, dispatch, and execution. · `src/models/command/mod.rs`
- [Command Dispatch](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/dispatcher.rs): dispatch · Routes command interactions to handlers. · `src/models/command/dispatcher.rs`
- [Command Responses](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/command/response/mod.rs): response building · Builds Discord-compatible command replies. · `src/models/command/response/mod.rs`
- [Autocomplete](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/autocomplete/mod.rs): interaction pipeline · Autocomplete request handling and suggestion responses. · `src/models/autocomplete/mod.rs`
- [Components](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/components/mod.rs): interaction pipeline · Message components and layout/content composition. · `src/models/components/mod.rs`
- [Modals](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/modals/mod.rs): interaction pipeline · Modal submission handling. · `src/models/modals/mod.rs`
- [Discord Models](https://github.com/gitginocchio/flarecord-rs/blob/main/src/models/mod.rs): schema types · Attachments, embeds, users, colors, and serializable payload helpers. · `src/models/mod.rs`

### Extensibility

Traits and application-defined command/component implementations.

- [Framework Traits](https://github.com/gitginocchio/flarecord-rs/blob/main/src/traits/mod.rs): abstractions · Pluggable behavior boundaries for components and value resolution. · `src/traits/mod.rs`

### Examples

Reference applications showing the framework in use.

- [Simple Bot](https://github.com/gitginocchio/flarecord-rs/blob/main/examples/simple/src/lib.rs): example app · Minimal Worker bot example. · `examples/simple/src/lib.rs`
- [Command Bot](https://github.com/gitginocchio/flarecord-rs/blob/main/examples/with_commands/src/lib.rs): example app · Example showing commands and components together. · `examples/with_commands/src/lib.rs`
- [Subcommands](https://github.com/gitginocchio/flarecord-rs/blob/main/examples/subcommands/src/lib.rs): example app · Nested command hierarchy example. · `examples/subcommands/src/lib.rs`
- [Components Demo](https://github.com/gitginocchio/flarecord-rs/blob/main/examples/components/src/lib.rs): example app · Example focused on interactive components. · `examples/components/src/lib.rs`

## Connections

- Public API → Prelude: re-exports · Public API exposes the prelude for consumers.
- Public API → Bot Core: builds on · Library entry points assemble the bot runtime.
- Public API → Interaction Base: exposes · Public API surfaces interaction types and builders.
- Bot Core → Bot Builder: configured by · Bot setup flows through a builder.
- Bot Core → Bot State: holds · Bot orchestration carries runtime state.
- Bot Core → Request Crypto: verifies · Incoming requests are authenticated before dispatch.
- Bot Core → Discord Service: syncs via · Bot orchestration talks to Discord REST services.
- Bot Core → Error Model: reports · Framework operations surface typed errors.
- Interaction Base → Commands: specializes to · Command interactions are one major interaction family.
- Interaction Base → Autocomplete: specializes to · Autocomplete interactions are routed separately.
- Interaction Base → Components: specializes to · Component interactions follow their own path.
- Interaction Base → Modals: specializes to · Modal submissions are isolated from other flows.
- Commands → Command Dispatch: dispatches through · Commands are routed to handlers after parsing.
- Commands → Command Responses: returns · Command execution produces structured responses.
- Commands → Framework Traits: uses · Commands rely on framework traits for extensibility.
- Autocomplete → Framework Traits: uses · Autocomplete handlers plug in through traits.
- Components → Framework Traits: uses · Component handlers are trait-based.
- Modals → Framework Traits: uses · Modal handling plugs into the trait boundary.
- Commands → Discord Models: reads · Commands are built on shared Discord schema types.
- Components → Discord Models: uses · Components reuse shared Discord data models.
- Discord Models → Discord Service: serializes for · Models are shaped for Discord API payloads.
- Discord Service → Error Model: returns · Service failures map into the framework error model.
- Request Crypto → Error Model: returns · Verification failures map into framework errors.
- Simple Bot → Public API: uses · Example apps consume the public library surface.
- Command Bot → Public API: uses · Example apps consume the public library surface.
- Subcommands → Commands: demonstrates · Shows nested command hierarchies.
- Components Demo → Components: demonstrates · Shows interactive component composition.
- Command Bot → Components: demonstrates · Shows combined command and component usage.
- Command Bot → Commands: demonstrates · Shows command registration and dispatch.