feat: update documentation for architecture, runtime scenarios, and deployment strategies

docs/08_concepts.md

@@ -1,32 +1,39 @@
 # Cross-cutting Concepts
 
-## Logging & Monitoring
+## Configuration and Validation
 
-- 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
+- Central config parsing in `src/config.ts` with typed getters and validation.
+- Required environment variables fail fast at startup.
+- Feature toggles gate optional services (admin API, dailies, OAuth sync).
 
-## Error Handling
+## Persistence Strategy
 
-- 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
+- PostgreSQL used for both high-volume mileage events and operational configuration.
+- Schema initialization runs inside service startup (`init` methods).
+- Strict null and row count checks protect runtime behavior under `exactOptionalPropertyTypes`.
 
-## Configuration
+## Security Model
 
-- 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
+- Admin API uses bearer token authentication middleware.
+- Health endpoint can be optionally public for infrastructure probes.
+- OAuth bridge performs code exchange server-side and stores ephemeral sessions in memory.
+- Secrets are environment-based and excluded from logs.
 
-## Security
+## Error Handling and Resilience
 
-- 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
+- Command handlers and API handlers return explicit user-safe errors.
+- Mileage persistence applies bounded retries for transient DB failures.
+- Dailies polling loop logs and continues on adapter-specific errors.
+- Shutdown hooks close HTTP/Discord/DB resources to avoid orphaned connections.
 
-## Conventions
+## Integration Concepts
 
-- Slash command names: kebab-case
-- Event handler naming: `on<EventName>` pattern
-- Database table names: snake_case, plural
-- PRs require passing lint + tests before merge
+- Discord integration points: slash commands, reactions, stage channels, role management.
+- Dashboard integration points: REST API JSON contracts and OAuth callback/session flow.
+- External content integration: adapter contract + webhook dispatcher for dailies.
+
+## Testing and Quality Gates
+
+- Jest + ts-jest for command and integration-like flows.
+- ESLint flat config for src and tests.
+- CI requires lint, build, and tests for backend plus lint/build for dashboard.