# renja-g/realm-warp architecture

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

- Interactive diagram: https://gitdiagram.com/renja-g/realm-warp
- Repository: https://github.com/renja-g/realm-warp

## Overview

##### API Service
- Located in the "api" directory.
- Provides endpoints (as documented in the README) for adding, deleting, and retrieving summoner details.
- Contains modules for configuration, database connections, security (JWT and password handling), schema definitions, and a router that connects various API endpoints like authentication, summoner management, and leaderboards.
- Uses an OpenAPI spec to ensure the API is fully typed and well documented.

##### Watcher Service
- Found in the "watcher" directory.
- Acts as the core component that continuously tracks summoner information, league data, and match history.
- Enhances match data with additional league information post-match.

##### RateLimiter Service
- Found in the "rate_limiter" directory.
- Implements a proxy rate limiter (using Pulsfire as mentioned in the README) to manage and throttle calls to the Riot API from all components of the system.

Additional elements include:
- A Docker Compose file that orchestrates these components into separate containers.
- Configuration files (.env.example, Dockerfiles, pyproject.toml, etc.) that indicate a well-defined environment and dependency isolation.
- A MongoDB back-end (mentioned in README under “Data schema”) that underpins the data persistence for summoners, league entries, and matches.

##### Interactions and Data Flow
- The API Service accesses the MongoDB for CRUD operations on summoner, league, and match collections.
- The Watcher Service retrieves and stores data from the Riot API, processing and enhancing match data before updating the MongoDB database.
- Both API and Watcher interact with the RateLimiter Service when they need to fetch data from the Riot API.

##### Incorporate Architectural Patterns and Design Principles
- That the project uses containerization – annotate Docker containers and show that the containers communicate (or are orchestrated) via Docker Compose.
- Modularization: the separation of concerns between the API (user interaction), Watcher (system monitoring and data enrichment), and RateLimiter (external API protection).
- Key design choices, like the use of dependency injection (as seen in the API’s “deps.py”) and schema validations (via requests and responses schemas).

##### Relevant Technical Details
- Use labels to indicate frameworks or technologies:
- The API uses Python (FastAPI is suggested by the structure and the use of “uv.lock”, which may hint at Uvicorn as the ASGI server).
- The use of Docker indicates containerized deployment.
- MongoDB is the underlying database.
- Security aspects are managed using JWT tokens and password hashing mechanisms.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Client["Client (REST Calls)"]:::client
    RiotAPI["Riot API"]:::external

    %% Container Orchestration
    subgraph "Container Orchestration"
        dockerCompose["Docker Compose"]
    end

    %% API Service Container
    subgraph "API Service Container"
        API["API Service\n(Auth, Summoner, Leaderboard)"]:::container
    end

    %% Watcher Service Container
    subgraph "Watcher Service Container"
        Watcher["Watcher Service\n(Tracking & Data Enhancement)"]:::container
    end

    %% RateLimiter Service Container
    subgraph "RateLimiter Service Container"
        RateLimiter["RateLimiter Service\n(External API Proxy)"]:::container
    end

    %% Database
    MongoDB["MongoDB\n(Data Persistence)"]:::database

    %% Data flow and Interactions
    Client -->|"POST_/summoner"| API
    API -->|"CRUD_Operations"| MongoDB
    API -->|"Calls_via_RateLimiter"| RateLimiter
    Watcher -->|"Fetches_Data_via_RateLimiter"| RateLimiter
    RateLimiter -->|"Proxies_Requests"| RiotAPI
    Watcher -->|"Updates_Data"| MongoDB

    %% Docker Compose orchestrates the containers
    dockerCompose -->|"Orchestrates"| API
    dockerCompose -->|"Orchestrates"| Watcher
    dockerCompose -->|"Orchestrates"| RateLimiter

    %% Styles
    classDef client fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef external fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef database fill:#e6ffe6,stroke:#228B22,stroke-width:2px;
    classDef container fill:#fff2cc,stroke:#c69500,stroke-width:2px;

    %% Click Events for Component Mapping
    click API "https://github.com/renja-g/realm-warp/tree/main/api/"
    click Watcher "https://github.com/renja-g/realm-warp/tree/main/watcher/"
    click RateLimiter "https://github.com/renja-g/realm-warp/tree/main/rate_limiter/"
    click dockerCompose "https://github.com/renja-g/realm-warp/blob/main/docker-compose.yml"
```
