40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
# 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.
|