Purpose and Scope

These guidelines apply to all parts of your Discord bot project (core logic, infrastructure, Discord layer, background jobs). They cover style, architecture, error handling, logging, data access, and observability, emphasizing maintainable, structured code.

Project Structure and Architecture

• Strictly separate layers: Domain/Core (business logic, entities, services, interfaces), Infrastructure (Postgres access, APIs, Sentry, Serilog sinks), Presentation/Discord (DSharpPlus commands, event handlers).
• Discord layer only handles orchestration and mapping—no business logic; delegate to core services via DI.
• Use Dependency Injection everywhere (IHost/HostBuilder); avoid static singletons except for stateless utilities.

C# Style and Naming Conventions

• Follow official .NET conventions: PascalCase for types/properties/methods/events, camelCase for parameters/private fields (optionally _camelCase).
• Async methods always end with Async suffix: GetGuildSettingsAsync.
• Use var when type is obvious on the right-hand side; explicit types for public APIs.
• Enable Nullable Reference Types (enable); prefer null checks over ! operator spam.

Async and Concurrency for Discord Bot

• Never block on async code (.Result, .Wait()); use async/await throughout, especially in DSharpPlus event handlers.
• Offload long-running tasks (polling, cron jobs) to BackgroundService/IHostedService, not event handlers.
• Propagate CancellationTokens where useful (DB calls, HTTP), especially in background jobs and shutdown handling.

Configuration, Secrets, and Environments

• Use IConfiguration/Options pattern exclusively: strongly-typed classes (BotOptions, DatabaseOptions, SentryOptions) via services.Configure.
• Never hardcode secrets (bot token, DB password, Sentry DSN): use User Secrets locally, environment vars or secret stores in production.
• Environment-specific files (appsettings.Development.json, appsettings.Production.json): verbose logging in dev, restrained in prod.

Logging with Serilog

• Always use structured logging, never string concatenation: Log.Information("User {UserId} invoked {CommandName}", userId, commandName).
• Centralize sinks/enrichers in Program.cs bootstrap: Console + rolling files, enriched with context (GuildId, UserId, ShardId) via LogContext.PushProperty.
• Define log levels clearly:

Level	Usage Example
Verbose	Detailed debug info (dev only)
Debug	Command payloads (no secrets)
Information	Business events (command executed, job completed)
Warning	Recoverable issues (retry, rate limit)
Error	Operation failures (non-fatal)
Fatal	Process-killing errors

Avoid logging sensitive data (tokens, full messages, PII).

PostgreSQL Data Access

• Abstract data access (Repository/CQRS/Service layer); never use NpgsqlConnection directly in handlers.
• Manage transactions/connections via using or ORM (EF Core/Dapper).
• Separate persistence entities (GuildSettingsEntity) from domain models (GuildSettings) with mappers.
• Keep migrations in repo; automate rollout (dotnet ef database update).

Error Handling and Sentry

• Handle errors close to source, but add global fallbacks (UnhandledException) for Sentry notifications.
• Distinguish expected errors (validation, NotFound) → warn/log, no Sentry; unexpected (NullRef, DB disconnect) → Error/Fatal + Sentry.
• Enrich Sentry with tags/extras (UserId, GuildId, CommandName); enable rate limiting/sampling.

DSharpPlus Discord-Specific Rules

• Keep event handlers lean: validate → map → call core service.
• Organize commands by domain (Moderation, Utility, Admin).
• Respect rate limits: cache aggressively (guild/member data), retry with backoff on limits.
• Centralize responses/texts for easy localization.

Testing, Quality, and Maintainability

• Unit tests: core services, mappers, helpers.
• Integration tests: data flows against test Postgres (containerized).
• Code review: no merge without review; small PRs; CI runs build/tests/format/analyzers.