Arquitectura
Arquitectura
System overview
The boundaries and main request path of ItsBagelBot.
En esta página
Scope and components
ItsBagelBot receives platform events, evaluates bot behaviour, and sends actions back to the platform. Broadcasters configure that behaviour through the dashboard. The services communicate over NATS; the data services own their schemas and expose operations rather than sharing database access.
flowchart LR
Twitch --> Ingress["Twitch ingress"]
Ingress -->|events| Sesame
Sesame -->|actions| Outgress
Outgress --> Twitch
Dashboard -->|RPC| Owners["Data services"]
Owners -->|change events| Projector
Projector --> Projection[("Valkey projection")]
Sesame --> Projection
The Twitch ingress is Elixir (app/twitch/ingress); Sesame and outgress are Go (app/twitch/sesame, app/twitch/outgress). The dashboard and admin apps live under web/.
This diagram is a starting point, not a complete dependency graph. See system state for the service map, data and state for ownership and consistency, and CONTEXT-MAP.md for the repository’s context boundaries. Deployment configuration is under deploy/.
Follow an event through the code
- Ingress receives Twitch events and publishes normalized messages. Subject and stream choices distinguish traffic lanes; see stream definitions.
- Sesame loads the channel context and applies module and command gates. A missing read-model entry can require an owner RPC; the projection client implements those reads.
- Sesame publishes an action for outgress, which carries out the platform request. An accepted message and a successful Twitch API action are separate outcomes.
The request path has deadlines and bounded retention. A consumer restart can resume retained work, but cannot recover messages already expired from a stream. Callers must handle unavailable dependencies and timeouts; see RPC contracts and settings projection.
Change a cross-service feature
Start with the owning service and its domain contract under internal/domain. Trace the publisher or RPC client, handler, storage and downstream consumers. Change both sides and their tests together; deployment permissions for subjects are in accounts.yaml. Keep backend access in the shared packages and review whether the new operation needs a durable result, a retry-safe effect or a disposable projection.