allucanget/omo-bot
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
zwitschi
2026-05-17 16:54:00 +02:00
parent a402c7b0bb
commit 168f4ea13c
5 changed files with 176 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/04_solution_strategy.md
+24 -22
View File
@@ -2,32 +2,34 @@
## Technology Decisions
| Decision | Choice | Rationale |
| ---------------- | -------------------- | --------------------------------------------------------------------------------------- |
| Bot framework | Discord.js (Node.js) | Mature library, strong type support, rich event model |
| Database | PostgreSQL | Reliable, supports JSONB for flexible user state, well-suited for mileage/role tracking |
| Frontend (Admin) | React | Team familiarity, rich ecosystem for dashboards |
| Hosting | Coolify | Easy deployment for Node.js with Nixpacks. |
| Auth | Discord OAuth2 | No custom auth needed, seamless web/bot integration |
| Decision | Choice | Rationale |
| -------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- |
| Bot runtime | Node.js + TypeScript + discord.js | Strong ecosystem, typed Discord interactions, shared language across backend/dashboard |
| Persistence | PostgreSQL (`pg`) | Reliable relational storage for mileage, schedules, and settings |
| Admin API | Express | Lightweight routing and middleware model for operational endpoints |
| Dashboard | React + Vite + TypeScript | Fast iteration and typed API integration |
| Authentication | Bearer token (admin API) + Discord OAuth2 | Secure machine-to-machine admin calls plus user identity bridge |
| Deployment | Coolify + Gitea Actions | Simple CI/CD path with webhook-triggered production rollout |
## Top-Level Decomposition
## Architectural Strategy
The system follows a **modular monolith** pattern with clear separation:
System uses modular monolith strategy in single backend process:
- **Core Bot** — command handlers, event listeners, Discord Gateway logic
- **Content Syndicator** — polling adapters for YouTube/IG/TikTok, webhook dispatch
- **Event Manager** — FIFO queue for stage/speaker management
- **Mileage Engine** — scoring logic, persistence, state sync with web app
- **Admin API** — RESTful endpoints for bot config, content scheduling, analytics
- Bot core orchestrates Discord gateway and command/event handling.
- Domain services encapsulate call-sheet onboarding, tour queue, mileage, and dailies.
- Operational interfaces exposed through Admin API and OAuth bridge.
- Shared configuration layer centralizes environment parsing and validation.
- Separate dashboard SPA consumes API without direct DB access.
## Key Quality Goals
## Quality Strategies
- **Availability** — Stateless bot instances scale horizontally behind load balancer
- **Consistency** — Write-ahead logging for mileage transactions; periodic state reconciliation with web app
- **Extensibility** — Adapter pattern for content sources: implement interface, register, deploy
- Availability: graceful startup/shutdown, service initialization guards, process-level health endpoint.
- Consistency: transactional mileage writes, strict DB row guards, idempotent schedule updates.
- Security: token-based admin auth, OAuth code exchange on server side, no token logging.
- Extensibility: adapter interface for new dailies sources and isolated service modules.
- Operability: CI checks (lint/build/test) for bot and dashboard before deploy trigger.
## Organizational Decisions
## Trade-offs
- One-person or small-team development per project scope
- CI/CD via Gitea Actions: lint → test → deploy
- Feature toggles for admin dashboard rollout
- In-memory OAuth sessions reduce complexity but require re-authentication after process restart.
- Modular monolith minimizes operational overhead now, while preserving service boundaries for future extraction.