# Cross-cutting Concepts

## Logging & Monitoring

- Structured logging (JSON) to stdout — visible in Coolify logs and via `docker logs`
- Log levels: DEBUG (dev), INFO (prod), ERROR (alert-worthy)
- Key metrics exposed via Prometheus endpoint: commands/sec, webhook latency, active users

## Error Handling

- Command handlers: try/catch → ephemeral error reply to user + logged
- Content pollers: exponential backoff on API failures, alert after 3 consecutive failures
- Mileage writes: retry (3x, 50ms backoff) before logging as failed

## Configuration

- Environment variables via `.env` file (dev) or Coolify secrets (prod), keep example in `.env.example`
- Config schema validated on startup — bot exits on missing required vars

## Security

- Bot token stored in env variable, never logged
- OAuth2 tokens short-lived; refresh flow managed by web app
- Admin dashboard routes guarded by Discord OAuth2 role check (`@Producer` or `@Director`)
- All external API calls over HTTPS

## Conventions

- Slash command names: kebab-case
- Event handler naming: `on<EventName>` pattern
- Database table names: snake_case, plural
- PRs require passing lint + tests before merge