feat: update documentation for architecture, runtime scenarios, and deployment strategies

2026-05-17 16:54:00 +02:00
parent a402c7b0bb
commit 168f4ea13c
5 changed files with 176 additions and 135 deletions
@@ -3,39 +3,53 @@
 ## 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      │    │
-│  └──────────────────────────────────────────────┘    │
-└──────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────┐
+│                         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  │
+                 └────────────────────────────┘
 ```

-### Black Box Descriptions
+## Building Blocks and Responsibilities

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