omo-bot/docs/05_building_block_view.md

Building Block View

Whitebox Overall System (Level 1)

┌────────────────────────────────────────────────────────────┐
│                         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)