omo-bot/docs/08_concepts.md

Cross-cutting Concepts

Configuration and Validation

• 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).

Persistence Strategy

• 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.

Security Model

• 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.

Error Handling and Resilience

• 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.

Integration Concepts

• 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.