# minhthong1410/realtime_ranking architecture

> Architecture diagram of the GitHub repository minhthong1410/realtime_ranking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minhthong1410/realtime_ranking
- Repository: https://github.com/minhthong1410/realtime_ranking

## Overview

##### Main Components
a. Entry Point/Command:
- Cmd/ directory and its main.go file, which serves as the starting point of the service.
- Top-level main.go as another starting entry if applicable.
b. API Layer:
- Internal/app/api package which includes the API entry points (router, error handling, etc.).
- Clearly denote the API routes and endpoints that will serve requests.
c. Handlers:
- Internal/handler package, particularly the components like ranking.go and error.go, which process business logic and implement real-time ranking.
d. Middleware:
- Pkg/middleware package - error_handler.go, log.go, and recovery.go. These are responsible for handling cross-cutting concerns such as error recovery, logging, and consistent error responses.
e. Utilities:
- Pkg/httputil for JSON handling and building standard HTTP responses.
- Pkg/logutil to centralize logging functionalities.
f. Data Layer / External Service:
- Pkg/redis as the component managing connectivity with Redis – a key element for real-time ranking where fast access and in-memory operations are likely critical.

##### Relationships and Interactions
- Client requests (HTTP) enter the system through the API layer.
- The API router directs the requests to the appropriate handlers (for ranking or error management).
- Handlers perform the business logic, including interacting with the Redis client from pkg/redis to update/read real-time ranking data.
- Middleware intercepts each request, providing logging, error handling, and recovery from any runtime exceptions.
- Utility packages (httputil and logutil) support the flow by managing HTTP responses and logs respectively.

##### Architectural Patterns and Design Principles
- The project follows a modular microservice design, separating concerns between command entry, API management, business logic (handlers), and cross-cutting middleware/utilities.
- There is a clear separation between the application layer (internal/app/api) and the utility/helper functions (pkg) ensuring reusability and maintainability.
- Using Redis for real-time ranking emphasizes a design optimized for fast, in-memory data operations and responsiveness.

##### Technologies and Frameworks
- Go as the primary programming language.
- Redis for data storage and retrieval pertinent to ranking logic, as indicated by pkg/redis.
- Standard Go packages for HTTP server functionalities, enhanced and structured by custom middleware implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CR("Client Request"):::client

    subgraph "Entry Point"
        EP1("cmd/main.go"):::entry
        EP2("main.go"):::entry
    end

    subgraph "API Layer"
        API("API Router"):::api
    end

    subgraph "Middleware"
        MW("Middleware: Logger/Recovery/Error"):::middleware
    end

    subgraph "Handlers"
        RH("Ranking Handler"):::handler
        EH("Error Handler"):::handler
    end

    subgraph "Utilities"
        HTTPU("HTTP Utility"):::util
        LOGU("Logging Utility"):::util
    end

    subgraph "Data Layer"
        REDIS("Redis Client"):::data
    end

    %% Connections
    CR --> MW
    EP1 --> API
    EP2 --> API
    MW --> API
    API --> RH
    API --> EH
    RH --> REDIS
    API --> HTTPU
    MW --> LOGU
    API --> LOGU

    %% Click Events
    click EP1 "https://github.com/minhthong1410/realtime_ranking/blob/main/cmd/main.go"
    click EP2 "https://github.com/minhthong1410/realtime_ranking/blob/main/main.go"
    click API "https://github.com/minhthong1410/realtime_ranking/tree/main/internal/app/api"
    click RH "https://github.com/minhthong1410/realtime_ranking/blob/main/internal/handler/ranking.go"
    click EH "https://github.com/minhthong1410/realtime_ranking/blob/main/internal/handler/error.go"
    click MW "https://github.com/minhthong1410/realtime_ranking/tree/main/pkg/middleware"
    click HTTPU "https://github.com/minhthong1410/realtime_ranking/tree/main/pkg/httputil"
    click LOGU "https://github.com/minhthong1410/realtime_ranking/tree/main/pkg/logutil"
    click REDIS "https://github.com/minhthong1410/realtime_ranking/blob/main/pkg/redis/redis_client.go"

    %% Styles
    classDef client fill:#ffe4e1,stroke:#333,stroke-width:2px;
    classDef entry fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef middleware fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef handler fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef util fill:#ffdab9,stroke:#333,stroke-width:2px;
    classDef data fill:#FFD700,stroke:#333,stroke-width:2px;
```
