Bot Architecture - Stars Components

A bot built with @wolfstar/http-framework is a small Node.js HTTP server plus a set of classes, called pieces, that the framework discovers on disk. This guide walks through the moving parts so you know where each piece of your bot belongs.

Want the package-level view instead? See Why Stars Components for how the packages stack, or the packages index for the full list.

Request Flow

Discord does not hold a connection to your bot. It sends every interaction as an HTTPS POST to the interactions endpoint you configured, and expects a reply to that same request.

Discord ──POST──▶ Client (node:http)
                    │  1. verify the request signature with DISCORD_PUBLIC_KEY
                    │  2. parse the interaction payload
                    ▼
                  Router
                    │  3. pick the piece that owns the interaction
                    ▼
      Command / InteractionHandler   ──▶ your code runs
                    │
                    ▼
                  reply ──▶ HTTP response (or a follow-up through @discordjs/rest)

The framework emits an event at each step (commandRun, commandSuccess, commandError, commandFinish, and the matching interactionHandler* and autocomplete* events), so cross-cutting concerns such as logging and error replies live in listeners instead of being repeated in every command. Expected failures, such as a denied precondition, go to the *Denied events instead of commandError.

Project Layout

A project scaffolded with @wolfstar/create-http-framework looks like this:

my-discord-bot/
├─ src/
│  ├─ commands/           # Command pieces: slash and context-menu commands
│  ├─ interaction-handlers/  # Buttons, select menus, modals
│  ├─ listeners/          # Reactions to client events (errors, HMR, ...)
│  ├─ lib/
│  │  └─ setup/           # Side-effect setup: logger, plugins, augmentations
│  ├─ locales/            # Translation files (when i18n is enabled)
│  └─ main.ts             # Entry point
├─ tests/                 # Interaction tests (when testing is enabled)
├─ stars.config.ts        # Build and dev configuration
└─ .env                   # DISCORD_TOKEN, DISCORD_PUBLIC_KEY

Each directory under the entry point’s folder is a store. client.load() scans every store, imports each file, and registers the exported classes. You never register a command by hand: creating the file is enough.

The scaffold generates commands/ (and lib/, locales/, tests/ depending on your choices). Add interaction-handlers/ and listeners/ when you need them. See Pieces below.

Entry Point

src/main.ts wires the pieces together. It runs the setup imports first, creates the client, loads the stores, publishes the command definitions, and starts the server:

import './lib/setup/all.js';

import { Client } from '@wolfstar/http-framework';

const client = new Client();

await client.load();
await client.registry.pushGlobalCommands();
await client.listen({ port: 3000 });

Order matters here. Anything with side effects — plugin /register imports, module augmentations, logger configuration — must be imported before new Client(), because the client reads that state while it is constructed. See Configuring the Client for how client.load() finds your stores.

Pieces

Everything your bot does is a piece: a class that extends a base type, lives in a store directory, and is loaded by the framework. The three you will use most:

Piece	Store	Runs when
`Command`	`commands`	A slash command, context-menu command, or autocomplete arrives
`InteractionHandler`	`interaction-handlers`	A component (button, select menu) or modal submit arrives
`Listener`	`listeners`	The client or another emitter fires a named event

Pieces are regular classes, which is what makes them easy to test in isolation and to reload without restarting the process. Configure them with @ApplyOptions and gate them with the Requires* decorators from @wolfstar/decorators instead of writing constructors and if checks. The Build a Command guide covers commands in depth.

Commands and the Registry

A command describes its Discord definition with @RegisterCommand, and the framework collects every definition in the application-command registry. Pushing the registry is what makes commands appear in Discord:

await client.registry.pushGlobalCommands();
await client.registry.pushGuildRestrictedCommands();

Because definitions and handlers sit in the same class, the shape Discord sees and the code that answers it cannot drift apart.

Listeners

A listener subscribes to a client event. The most common use is turning errors into replies and log lines in one place:

import { ApplyOptions } from '@wolfstar/decorators';
import { Events, Listener, type ClientEventCommandContext } from '@wolfstar/http-framework';

@ApplyOptions<Listener.Options>({ event: Events.CommandError })
export class UserListener extends Listener {
	public run(error: unknown, context: ClientEventCommandContext) {
		this.container.logger.error(`Failed to run ${context.command.name}`, error);
	}
}

The Container

Pieces reach shared services through container instead of importing singletons or receiving them through constructors. container.logger, the client, and the stores are available as soon as @wolfstar/http-framework is imported. Your own services join them by augmenting the Container interface and assigning the value during setup, so a command can use this.container.database with full type safety.

Extending the Bot

Optional capabilities are added as plugins, imported through a /register entry point during setup:

Need	Add
Translations for users and guilds	`@wolfstar/plugin-i18next`
A REST API next to interaction handling	`@wolfstar/plugin-api`
Modular subcommands in separate classes	`@wolfstar/plugin-subcommands-advanced`
Typed environment variables	`@wolfstar/env-utilities`
Drop-in commands and listeners	`@wolfstar/shared-http-pieces`

Plugins are released from the wolfstar-project/plugins repository; the Plugins guide explains how registration works.

@wolfstar/http-framework-i18n has been removed. Use @wolfstar/plugin-i18next instead. See the migration guide.

Testing the Bot

Since a command is a plain class, @wolfstar/http-framework-test-utils can dispatch a typed interaction fixture at it and assert on the reply, with no HTTP server and no Discord. Follow Testing Interactions to add tests as the command set grows.

Public API

Every package exposes its supported API through src/index.ts and explicit package.json export maps. The API reference is generated from those entry points on every documentation build, so private implementation files do not become accidental public contracts.

​Request Flow

​Project Layout

​Entry Point

​Pieces

​Commands and the Registry

​Listeners

​The Container

​Extending the Bot

​Testing the Bot

​Public API

Request Flow

Project Layout

Entry Point

Pieces

Commands and the Registry

Listeners

The Container

Extending the Bot

Testing the Bot

Public API