56 lines
3.9 KiB
Markdown
56 lines
3.9 KiB
Markdown
# Building Block View
|
|
|
|
## Whitebox Overall System (Level 1)
|
|
|
|
```txt
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ omo-bot │
|
|
├────────────────────────────────────────────────────────────┤
|
|
│ Discord Gateway Runtime │
|
|
│ ├─ Command handlers (/ping, /call-sheet, /sign-up, /dailies) │
|
|
│ ├─ Reaction/member event handlers │
|
|
│ └─ Service orchestration (`startBot`) │
|
|
│ │
|
|
│ Core Services │
|
|
│ ├─ Call Sheet Service │
|
|
│ ├─ Tour Schedule Engine │
|
|
│ ├─ Mileage Engine │
|
|
│ ├─ Dailies Service (adapters + dispatcher) │
|
|
│ ├─ OAuth Bridge Service │
|
|
│ └─ Configuration Database Service │
|
|
│ │
|
|
│ Interfaces │
|
|
│ ├─ Admin API (Express) │
|
|
│ └─ Health endpoint │
|
|
└──────────────────────────────┬─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────┐
|
|
│ PostgreSQL + Discord APIs │
|
|
└────────────────────────────┘
|
|
```
|
|
|
|
## Building Blocks and Responsibilities
|
|
|
|
| Building Block | Responsibility |
|
|
| ------------------------------- | ---------------------------------------------------------------------------------- |
|
|
| `src/bot.ts` | Runtime bootstrap, command registration, service lifecycle, graceful shutdown |
|
|
| `src/call-sheet.ts` | Reaction-role onboarding, grouped role exclusivity, welcome flow hooks |
|
|
| `src/tour-schedule.ts` | Queue state, join/leave/advance operations, stage speaker management |
|
|
| `src/mileage.ts` | Event scoring, persistence, mileage aggregation, role tier synchronization |
|
|
| `src/dailies/service.ts` | Polling scheduler, adapter orchestration, webhook dispatch loop |
|
|
| `src/oauth-bridge.ts` | Discord OAuth code exchange, user fetch, temporary session cache, optional sync |
|
|
| `src/configuration-database.ts` | Settings/schedules CRUD and engagement snapshot persistence |
|
|
| `src/admin-api.ts` | Authenticated operational endpoints for config, queue, stats, OAuth, and config DB |
|
|
| `admin-dashboard/src/*` | Browser UI for OAuth connect flow, API calls, and analytics views |
|
|
|
|
## Level 2 (Admin API)
|
|
|
|
Admin API route groups:
|
|
|
|
- Health and runtime config (`/health`, `/admin/config`)
|
|
- Tour schedule operations (`/admin/schedule`, `/admin/schedule/clear`)
|
|
- Engagement statistics (`/admin/stats`, `/admin/db/engagement/latest`)
|
|
- Configuration DB CRUD (`/admin/db/settings`, `/admin/db/schedules`)
|
|
- OAuth bridge session flow (`/admin/oauth/discord/exchange`, `/admin/oauth/session/:sessionId`)
|