# 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`)