# twirapp/twir architecture

> Architecture diagram of the GitHub repository twirapp/twir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/twirapp/twir
- Repository: https://github.com/twirapp/twir

## Overview

##### High-Level Architecture Components

a. Frontend Layer:
- Dashboard application (Vue.js)
- Public page application
- Overlays application
- Landing page (Nuxt.js)

b. Backend Services:
- API Gateway (GraphQL)
- Multiple microservices:
- Bots service
- Events service
- Parser service
- WebSockets service
- Timers service
- EventSub service
- Integrations service
- Tokens service
- YTSR (YouTube Search) service

c. Infrastructure:
- PostgreSQL database
- Redis cache
- MinIO object storage
- NATS message broker
- Temporal workflow engine

**┌─────────────────────────────────────────────────────────────┐**
- Client Layer                            │
- ┤
- API Layer                               │
- ┤
- Service Layer                           │
- ┤
- Data Layer                              │
- ┘

##### Key Relationships to Highlight

a. Client-API Communication:
- GraphQL API gateway for dashboard
- REST endpoints for public access
- WebSocket connections for real-time features

b. Service Communication:
- NATS message broker for inter-service communication
- Temporal for workflow orchestration
- Event-driven architecture patterns

c. Data Flow:
- Database access patterns
- Caching strategy
- File storage interactions

##### Specific Implementation Details

- Rectangles for services
- Hexagons for message brokers
- Clouds for external services (Twitch, Discord, etc.)

- Blue: Frontend applications
- Green: Backend services
- Yellow: Infrastructure components
- Red: External services

##### Critical Flows

a. Authentication Flow:
- Twitch OAuth integration
- Token management
- Session handling

b. Real-time Features:
- WebSocket connections
- Event subscription handling
- Chat bot interactions

c. Data Processing:
- Command parsing
- Event handling
- Timer management

##### Deployment Context

How the system can be deployed:
- Docker container boundaries
- Network segmentation
- Load balancer placement
- Service discovery mechanisms

Remember to include:
- Service names and versions
- Communication protocols
- Data store types
- External service dependencies
- Security boundaries
- Scaling points
- Monitoring interfaces

This will provide a clear understanding of the system's architecture while maintaining enough detail for technical discussions and implementation guidance.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef infrastructure fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#e74c3c,stroke:#c0392b,color:white
    classDef library fill:#9b59b6,stroke:#8e44ad,color:white

    %% Client Layer
    subgraph ClientLayer["Client Applications"]
        Dashboard["Dashboard (Vue.js)"]:::frontend
        PublicPage["Public Page"]:::frontend
        Overlays["Overlays"]:::frontend
        Landing["Landing Page (Nuxt.js)"]:::frontend
    end

    %% API Layer
    subgraph APILayer["API Gateway"]
        GraphQL["GraphQL Gateway"]:::backend
        WSGateway["WebSocket Gateway"]:::backend
    end

    %% Service Layer
    subgraph ServiceLayer["Microservices"]
        Bots["Bots Service"]:::backend
        Events["Events Service"]:::backend
        Parser["Parser Service"]:::backend
        WebSockets["WebSockets Service"]:::backend
        Timers["Timers Service"]:::backend
        EventSub["EventSub Service"]:::backend
        Integrations["Integrations Service"]:::backend
        Tokens["Tokens Service"]:::backend
        YTSR["YTSR Service"]:::backend
    end

    %% Infrastructure Layer
    subgraph InfraLayer["Infrastructure"]
        PostgreSQL[(PostgreSQL)]:::infrastructure
        Redis[(Redis Cache)]:::infrastructure
        MinIO[(MinIO Storage)]:::infrastructure
        NATS{{"NATS Broker"}}:::infrastructure
        Temporal{{"Temporal Engine"}}:::infrastructure
    end

    %% External Services
    subgraph ExternalServices["External Services"]
        Twitch["Twitch API"]:::external
        Discord["Discord"]:::external
        YouTube["YouTube"]:::external
    end

    %% Libraries
    subgraph CoreLibs["Core Libraries"]
        Models["Database Models"]:::library
        BusCore["Message Bus"]:::library
        Cache["Cache Layer"]:::library
        Config["Configuration"]:::library
        Repos["Repositories"]:::library
    end

    %% Relationships
    Dashboard --> GraphQL
    PublicPage --> GraphQL
    Overlays --> WSGateway
    Landing --> GraphQL

    GraphQL --> ServiceLayer
    WSGateway --> WebSockets

    ServiceLayer --> NATS
    ServiceLayer --> PostgreSQL
    ServiceLayer --> Redis
    ServiceLayer --> MinIO
    ServiceLayer --> Temporal

    Integrations --> ExternalServices
    EventSub --> Twitch
    YTSR --> YouTube

    ServiceLayer --> CoreLibs

    %% Click Events
    click Dashboard "https://github.com/twirapp/twir/tree/main/frontend/dashboard/"
    click PublicPage "https://github.com/twirapp/twir/tree/main/frontend/public-page/"
    click Overlays "https://github.com/twirapp/twir/tree/main/frontend/overlays/"
    click Landing "https://github.com/twirapp/twir/tree/main/web/"
    click GraphQL "https://github.com/twirapp/twir/tree/main/apps/api-gql/"
    click Bots "https://github.com/twirapp/twir/tree/main/apps/bots/"
    click Events "https://github.com/twirapp/twir/tree/main/apps/events/"
    click Parser "https://github.com/twirapp/twir/tree/main/apps/parser/"
    click WebSockets "https://github.com/twirapp/twir/tree/main/apps/websockets/"
    click Timers "https://github.com/twirapp/twir/tree/main/apps/timers/"
    click EventSub "https://github.com/twirapp/twir/tree/main/apps/eventsub/"
    click Integrations "https://github.com/twirapp/twir/tree/main/apps/integrations/"
    click Tokens "https://github.com/twirapp/twir/tree/main/apps/tokens/"
    click YTSR "https://github.com/twirapp/twir/tree/main/apps/ytsr/"
    click Models "https://github.com/twirapp/twir/tree/main/libs/gomodels/"
    click BusCore "https://github.com/twirapp/twir/tree/main/libs/bus-core/"
    click Cache "https://github.com/twirapp/twir/tree/main/libs/cache/"
    click Config "https://github.com/twirapp/twir/tree/main/libs/config/"
    click Repos "https://github.com/twirapp/twir/tree/main/libs/repositories/"
```
