Add initial project structure, including README, CONTRIBUTING, and documentation files

- Created .gitignore to exclude unnecessary files - Added README.md with project description and core features - Introduced CONTRIBUTING.md for development guidelines - Established documentation files for architecture, quality requirements, and technical risks
2026-05-17 15:50:43 +02:00
commit 77e43a6a38
16 changed files with 692 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 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                                     |