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