# lorenzofavaro/prompt-clash-game architecture

> Architecture diagram of the GitHub repository lorenzofavaro/prompt-clash-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lorenzofavaro/prompt-clash-game
- Repository: https://github.com/lorenzofavaro/prompt-clash-game

## Overview

##### Main Components
- Chat Service – Manages user interactions and image generation. It uses Chainlit for chat handling, includes its own API endpoints and data layer (e.g., mysql_data_layer, OCI storage client) and communicates with external AI services (OpenAI DALL-E).
- Round Manager Service – This service is responsible for handling game rounds, themes, timings, and state management. It houses modules for MySQL connection, round state repository, and a streaming component for real-time notifications.
- Admin Service and Admin Interface – The Admin Service provides backend functionality for administrative operations (e.g., evaluating and selecting winning images). Its corresponding Admin Interface is built using Streamlit, with components to render control buttons, images, login forms, and settings.
- User Interface – A React-based frontend that includes a full client application with multiple pages, API integrations, and state management. It is architectured to interact with the chat service through RESTful calls.
- Database Service – A MySQL database that persists game data. The README also mentions that a PostgreSQL alternative is possible.
- External Storage Providers – The implementation currently uses Oracle Cloud Infrastructure (OCI), with notes for alternative providers (AWS S3, GCS, Azure Blob).

##### Relationships and Interactions
- The User Interface communicates with the Chat Service (for image generation and chat interactions) as well as with other services as needed.
- Chat Service interfaces with the Database for persistence and uses specific data-layer modules (like the custom MySQL data layer) and storage clients.
- Round Manager Service orchestrates game rounds and communicates with both the Chat and Admin Services for real-time updates and administrative controls.
- Admin Service coordinates with the Admin Interface to present game data, timings, and controls to game administrators.
- All microservices are containerized (each service includes its Dockerfile and related configuration), and docker-compose is used to manage inter-service orchestration.

##### Architectural Patterns and Technologies
- The project is structured based on a microservices architecture:
- Each service (chat, round manager, admin) is isolated with its own codebase, Docker configuration, and runtime.
- The React-based User Interface and Streamlit-based Admin Interface emphasize a clear separation of client responsibilities.
- Use of containerization (Dockerfiles per service) implies a cloud-native design that can leverage orchestrators.
- API gateways or routers exist within each microservice (for instance, chat_router in chat_service, round_router in admin_service, etc.) to encapsulate endpoints.
- The design promotes separation of concerns through service-specific directories and dedicated configuration files.
- Additional libraries and frameworks include Chainlit (for chat service), Streamlit (for admin interface), and React (for user interface).

##### Elements
- Components: Label nodes for "Chat Service", "Round Manager Service", "Admin Service", "User Interface (React)", "Admin Interface (Streamlit)", and "Database (MySQL)/Storage".
- Data flow from the User Interface to the Chat Service.
- Communication from the Round Manager Service to both Chat and Admin Services.
- Interactions between each service and the Database.
- External calls to the OpenAI API from the Chat Service.
- Dependencies of the admin/dashboard side that interacts with administrative APIs.

## Diagram (Mermaid)

```mermaid
flowchart TB

    %% Client Layer
    subgraph "User Interface (React)"
        UI["User Interface (React)"]:::frontend
        uiApp["App.tsx"]:::frontend
        uiHome["Home.tsx"]:::frontend
        uiPkg["package.json"]:::frontend
        UI --> uiApp
        UI --> uiHome
        UI --> uiPkg
    end

    subgraph "Admin Interface"
        AdminI["Admin Interface (Streamlit)"]:::frontend
        adminInterfaceApp["app.py"]:::frontend
        adminInterfaceAPI["admin_api.py"]:::frontend
        adminInterfaceController["round_controller.py"]:::frontend
        AdminI --> adminInterfaceApp
        AdminI --> adminInterfaceAPI
        AdminI --> adminInterfaceController
    end

    %% Microservices Layer
    subgraph "Chat Service"
        ChatS["Chat Service"]:::backend
        chatApp["app.py"]:::backend
        chatMysql["mysql_data_layer.py"]:::backend
        chatOCI["oci_storage_client.py"]:::backend
        chatRouter["chat_router.py"]:::backend
        ChatS --> chatApp
        ChatS --> chatMysql
        ChatS --> chatOCI
        ChatS --> chatRouter
    end

    subgraph "Round Manager Service"
        RMS["Round Manager Service"]:::backend
        rmApp["app.py"]:::backend
        rmManager["round_manager.py"]:::backend
        rmMysql["mysql_connection.py"]:::backend
        rmState["round_state_repository.py"]:::backend
        rmSocket["socket_manager.py"]:::backend
        RMS --> rmApp
        RMS --> rmManager
        RMS --> rmMysql
        RMS --> rmState
        RMS --> rmSocket
    end

    subgraph "Admin Service"
        AdminS["Admin Service"]:::backend
        adminApp["app.py"]:::backend
        adminChatRouter["chat_router.py"]:::backend
        adminRoundRouter["round_router.py"]:::backend
        adminRoundService["round_service.py"]:::backend
        AdminS --> adminApp
        AdminS --> adminChatRouter
        AdminS --> adminRoundRouter
        AdminS --> adminRoundService
    end

    %% Container Orchestration
    Docker["Docker Compose"]:::container

    %% Infrastructure Layer
    subgraph "Infrastructure"
        Database["Database (MySQL)"]:::external
        Dalle["DALL-E API (OpenAI)"]:::external
        CloudStorage["Cloud Storage (OCI)"]:::external
    end

    %% Connections between layers
    UI -->|"REST_calls"| ChatS
    AdminI -->|"API_calls"| AdminS
    RMS -->|"updates"| ChatS
    RMS -->|"notifications"| AdminS

    ChatS -->|"persists"| Database
    RMS -->|"persists"| Database
    AdminS -->|"persists"| Database

    ChatS -->|"calls"| Dalle
    ChatS -->|"stores"| CloudStorage

    Docker --> ChatS
    Docker --> RMS
    Docker --> AdminS

    %% Styles
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px
    classDef backend fill:#f9f,stroke:#333,stroke-width:2px
    classDef external fill:#cff,stroke:#333,stroke-width:2px
    classDef container fill:#fcf,stroke:#333,stroke-width:2px

    %% Click Events for Chat Service Modules
    click chatApp "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/chat_service/app.py"
    click chatMysql "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/chat_service/data/mysql_data_layer.py"
    click chatOCI "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/chat_service/data/oci_storage_client.py"
    click chatRouter "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/chat_service/routers/chat_router.py"

    %% Click Events for Round Manager Service Modules
    click rmApp "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/round_manager_service/app.py"
    click rmManager "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/round_manager_service/core/round/round_manager.py"
    click rmMysql "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/round_manager_service/core/data/mysql_connection.py"
    click rmState "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/round_manager_service/core/data/round_state_repository.py"
    click rmSocket "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/round_manager_service/core/streaming/socket_manager.py"

    %% Click Events for Admin Service Modules
    click adminApp "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_service/app.py"
    click adminChatRouter "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_service/routers/chat_router.py"
    click adminRoundRouter "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_service/routers/round_router.py"
    click adminRoundService "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_service/services/round_service.py"

    %% Click Events for Admin Interface Modules
    click adminInterfaceApp "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_interface/app.py"
    click adminInterfaceAPI "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_interface/api/admin_api.py"
    click adminInterfaceController "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/admin_interface/pages/round_controller.py"

    %% Click Events for User Interface (React) Modules
    click uiApp "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/user_interface/app/src/App.tsx"
    click uiHome "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/user_interface/app/src/pages/Home.tsx"
    click uiPkg "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/user_interface/app/package.json"

    %% Click Event for Database Schema
    click Database "https://github.com/lorenzofavaro/prompt-clash-game/blob/main/init.sql"
```
