# Solution Strategy

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

## Top-Level Decomposition

The system follows a **modular monolith** pattern with clear separation:

- **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

## Key Quality Goals

- **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

## Organizational Decisions

- One-person or small-team development per project scope
- CI/CD via Gitea Actions: lint → test → deploy
- Feature toggles for admin dashboard rollout