Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
313 lines (243 loc) · 7.61 KB

ARCHITECTURE.md

File metadata and controls

313 lines (243 loc) · 7.61 KB
Raw

ARCHITECTURE.md

This document describes the current state and target architecture for Basely.

Basely is a Spring Boot Discord bot boilerplate using JDA. It is intended to provide a clean foundation for commands, moderation, role management, welcome messages, scheduled jobs, and automation.

Current Repository State

The repository is currently a lightweight starter. The important existing files are:

.
├── .gitignore
├── CONTRIBUTING.md
├── SECURITY.md
├── license.md
├── pom.xml
├── readme.md
└── src/
    └── test/
        └── java/
            └── com/
                └── discordbot/
                    └── DiscordBotApplicationTests.java

The Maven configuration defines:

  • Java 21
  • Spring Boot 3.5.13
  • Spring Web
  • JDA 5.0.0-beta.23
  • Spring Boot Test
  • Spring Data JPA
  • MySQL runtime driver

The visible codebase may not yet include the main Spring Boot application class or full bot implementation. Future architecture should be added incrementally and tested as features are implemented.

Architectural Direction

Basely should follow a simple layered architecture:

Discord Gateway / JDA Events
        ↓
Bot Gateway / Listener Layer
        ↓
Command and Event Routing
        ↓
Feature Handlers
        ↓
Domain Services
        ↓
Repositories / External APIs

The key design principle is separation of concerns:

  • JDA setup should not contain business logic.
  • Event listeners should dispatch to handlers, not perform large workflows inline.
  • Commands should validate input and delegate work.
  • Moderation actions should be guarded by permission checks.
  • Persistence should be isolated behind repositories and services.

Recommended Package Structure

Use com.discordbot as the root package.

src/main/java/com/discordbot/
├── DiscordBotApplication.java
├── config/
│   ├── DiscordBotProperties.java
│   └── JdaConfig.java
├── bot/
│   ├── BotStartupService.java
│   └── DiscordEventListener.java
├── commands/
│   ├── Command.java
│   ├── CommandContext.java
│   ├── CommandRegistry.java
│   ├── CommandRouter.java
│   └── impl/
├── events/
│   ├── GuildMemberJoinHandler.java
│   ├── MessageReceivedHandler.java
│   └── ReadyEventHandler.java
├── moderation/
│   ├── ModerationService.java
│   ├── PermissionService.java
│   └── WarnService.java
├── scheduler/
│   └── ReminderScheduler.java
├── services/
│   ├── WelcomeMessageService.java
│   └── RoleService.java
├── entities/
│   ├── GuildConfig.java
│   ├── WarningRecord.java
│   └── Reminder.java
├── repositories/
│   ├── GuildConfigRepository.java
│   ├── WarningRecordRepository.java
│   └── ReminderRepository.java
├── dto/
└── exceptions/

This structure is recommended, not mandatory. Do not create unused packages.

Application Startup Flow

Target startup flow:

Spring Boot starts
        ↓
Configuration properties load from environment/application properties
        ↓
JDA bean is created with token and required gateway intents
        ↓
Discord event listeners are registered
        ↓
Bot becomes ready
        ↓
Ready event logs safe startup metadata

The Discord token must come from configuration. It must never be hardcoded.

Recommended configuration keys:

discord.bot.token=${DISCORD_BOT_TOKEN}
discord.bot.prefix=!
discord.bot.enabled=true

Database configuration should also be environment-backed:

spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

Command Handling Design

A command should be a small unit of behavior.

Recommended contract:

public interface Command {
    String name();
    String description();
    void execute(CommandContext context);
}

Routing flow:

MessageReceivedEvent
        ↓
Ignore bots and webhooks
        ↓
Check configured prefix or slash-command type
        ↓
Parse command name and arguments
        ↓
Resolve command from registry
        ↓
Validate permissions and input
        ↓
Execute command
        ↓
Reply safely

Do not put large command logic inside the raw JDA listener.

Event Handling Design

Event handlers should be focused and idempotent where possible.

Examples:

  • GuildMemberJoinHandler sends welcome messages or assigns default roles.
  • ReadyEventHandler logs safe startup information.
  • MessageReceivedHandler delegates command parsing.

Avoid writing one large listener class that handles all Discord events.

Moderation Design

Moderation must be explicit and auditable.

Recommended flow:

Moderation command received
        ↓
Validate actor permissions
        ↓
Validate bot permissions
        ↓
Validate target user and guild context
        ↓
Execute JDA moderation action
        ↓
Persist warning/audit record if applicable
        ↓
Send safe confirmation message

Rules:

  • Do not allow users to moderate themselves unless explicitly designed.
  • Do not allow moderation of users with equal or higher roles where Discord hierarchy prevents it.
  • Always check the bot's own permissions before attempting an action.
  • Avoid storing private message content unless necessary.

Persistence Design

Use Spring Data JPA only for data that needs persistence.

Potential entities:

  • Guild configuration
  • Warning records
  • Reminder jobs
  • Custom command definitions
  • Audit records

Avoid storing unnecessary Discord personal data. Store Discord IDs as strings to avoid numeric overflow and preserve exact values.

Example fields for guild config:

guildId
commandPrefix
welcomeChannelId
welcomeMessageTemplate
defaultRoleId
enabled
createdAt
updatedAt

Scheduling Design

For simple reminders, Spring scheduling can be enough. For durable reminders that survive restarts, store them in the database and poll due reminders safely.

Avoid overengineering with external queue systems unless the project explicitly needs them.

Error Handling

Handle errors at feature boundaries:

  • Invalid command input should return a helpful Discord reply.
  • Permission errors should be clear but not leak internals.
  • JDA failures should be logged without tokens or sensitive payloads.
  • Database failures should not crash unrelated bot operations.

Logging Rules

Log safe operational information:

  • Startup success/failure
  • Guild count
  • Command registration summary
  • Feature enable/disable status
  • Moderation action type and non-sensitive IDs

Never log:

  • Bot token
  • Full authorization headers
  • Private messages
  • Database passwords
  • Complete user content from DMs

Testing Strategy

Current test coverage is minimal. Future changes should add tests around pure logic first.

Recommended tests:

  • Command parsing
  • Command registry behavior
  • Permission service logic
  • Moderation validation
  • Guild config defaults
  • Reminder due-date logic

Avoid relying on live Discord connections in unit tests. Mock or isolate JDA-dependent boundaries.

What AI Agents Must Not Assume

AI agents must not assume that the following already exist unless they are present in the working tree:

  • DiscordBotApplication.java
  • JDA configuration class
  • command registry
  • moderation commands
  • role management service
  • database entities
  • repositories
  • scheduler implementation
  • application properties

When adding these, implement them incrementally and keep changes aligned with the README promise.