# Building Block View

## Whitebox Overall System (Level 1)

```txt
┌──────────────────────────────────────────────────────┐
│                    omo-bot                           │
├──────────────────────────────────────────────────────┤
│  ┌──────────────────┐   ┌─────────────────────────┐  │
│  │   Command Layer  │   │   Event Listener Layer  │  │
│  │  /sign-up, /map  │   │  member_join, reaction  │  │
│  └────────┬─────────┘   └───────────┬─────────────┘  │
│           │                        │                 │
│           ▼                        ▼                 │
│  ┌──────────────────────────────────────────────┐    │
│  │              Service Layer                   │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────┐  │    │
│  │  │  Event   │ │ Mileage  │ │  Content     │  │    │
│  │  │ Manager  │ │ Engine   │ │  Syndicator  │  │    │
│  │  └──────────┘ └──────────┘ └──────────────┘  │    │
│  └───────────────────┬──────────────────────────┘    │
│                      │                               │
│                      ▼                               │
│  ┌──────────────────────────────────────────────┐    │
│  │            Data / Persistence Layer          │    │
│  │   PostgreSQL DB  +  Discord API Wrapper      │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘
```

### Black Box Descriptions

| Building Block     | Responsibility                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------ |
| Command Layer      | Register and handle slash commands (`/sign-up`, `/map`, `/help`); validate permissions     |
| Event Listener     | Subscribe to Discord Gateway events (member join, reaction add, voice state change)        |
| Event Manager      | Manage FIFO queue for voice/stage speakers; schedule "Tour Stop" events via Discord API    |
| Mileage Engine     | Score user interactions, persist to DB, trigger role upgrades, sync with web app           |
| Content Syndicator | Poll YouTube/IG/TikTok APIs; format rich embeds; dispatch to Discord channels via webhooks |
| Admin API          | Expose REST endpoints for dashboard (configuration, content schedule, engagement stats)    |
| DB Layer           | PostgreSQL connection pool, migrations, query builders                                     |