# minhhuy14/vou-be architecture

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

- Interactive diagram: https://gitdiagram.com/minhhuy14/vou-be
- Repository: https://github.com/minhhuy14/vou-be

## Overview

The project is a microservices-based, full-stack application composed of multiple self-contained services that communicate via an API gateway and use various external dependencies and building blocks. The overall architecture follows a modern distributed system approach with clear separation of concerns among the services.

##### Main Components
- API Gateway: Hosted in the "src/ApiGateway" folder. This service aggregates routes and forwards requests to the individual services.
- Authentication Service (AuthServer): Found under "src/AuthServer". Responsible for managing user identities, issuing tokens, and handling roles such as Admin, Player, and CounterPart.
- Event Service: Located under "src/EventService". Handles event management, notifications, related queries, and management commands.
- Game Service: Located under "src/GameService". Manages game-specific functions and real-time interactions, including SignalR hubs for quiz sessions and notifications.
- Background Jobs Service: Found under "src/BackgroundServiceJobs". Executes background scheduled and event-driven tasks like event status checks and quiz session jobs.
- Shared Building Blocks: In "src/BuildingBlocks" – these are common libraries and domain models (e.g., shared contracts, repositories, middleware, caching, etc.) that promote consistency and reuse across the microservices.
- External Infrastructure Components: Include several Docker Compose-based components such as PostgreSQL, Redis (both for caching and pub/sub), Zipkin for distributed tracing, Prometheus for monitoring, Elasticsearch/Kibana for logging and search. Configuration files for these exist under the "components" directory.

##### Relationships and Interactions
- The API Gateway acts as the unified entry point for all API calls, routing incoming requests to the appropriate downstream services.
- AuthServer provides authentication and authorization. It issues JWT tokens that are consumed by the other services to validate user requests.
- Event Service, Game Service, and Background Jobs interact with one another via messaging patterns. Services like Event Service and Background Jobs use a PubSub pattern (see Redis pub/sub YAMLs) for event notifications.
- SignalR endpoints for real-time communication in Event and Game services are clearly defined. For example, player notifications and real-time updates are pushed through websocket endpoints managed via the API gateway.
- Shared libraries and service invocations (through BuildingBlocks) are used across services to standardize error handling, logging, caching, and validation.
- External systems such as PostgreSQL, Redis, and other monitoring/tracing/logging tools are integrated via Docker containers.

##### Architectural Patterns & Design Principles
- Microservices architecture: Each functional area (authentication, events, games, background jobs) is developed as an independent service.
- API Gateway pattern: Simplifies client access and acts as a central routing and security enforcement point.
- Domain Driven Design: Clear separation of Commands, Queries, and Domain models indicates a CQRS-like approach in several services.
- Use of Distributed Messaging and PubSub: Noted in components and within services for event propagation.
- Containerization and orchestration via Docker Compose and Tye: Ensures each service is independently deployable and can be scaled as needed.
- Observability: Monitoring (Prometheus) and tracing (Zipkin) are integrated, with logging via Elasticsearch and Kibana, allowing for robust debugging and performance tracking.

- API Gateway
- AuthServer (Identity Service)
- Event Service
- Game Service
- Background Jobs Service
- Shared Building Blocks (can be represented as a shared library layer that several services consume)
- External infrastructure such as PostgreSQL, Redis, Prometheus, Zipkin, Elasticsearch/Kibana.
- Client requests enter via the API Gateway and are forwarded to the appropriate services.
- Data flows from AuthServer providing authentication tokens to other services.
- Event flow between Event Service, Background Jobs, and PubSub systems (Redis).
- SignalR/websocket real-time communication routes.
- Inter-service communications (synchronous REST calls or asynchronous messaging).
- Annotations for ports (as per the README) to indicate how the services are exposed (e.g., API Gateway on port 5000, AuthServer on port 5100, etc.).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Top layer: Client and API Gateway
    Client["Client Requests"]:::client
    API_GW["API Gateway (Port:5000)"]:::api

    %% Services Layer
    Auth["Authentication Service (AuthServer) (Port:5100)"]:::service
    Event["Event Service (Port:5200)"]:::service
    Game["Game Service (Port:5300)"]:::service
    Background["Background Jobs Service (Port:5400)"]:::service
    Shared["Shared Building Blocks"]:::shared

    %% External Infrastructure Layer
    Postgres["PostgreSQL"]:::database
    Redis["Redis (PubSub & Cache)"]:::database
    Zipkin["Zipkin (Tracing)"]:::externalInfra
    Prometheus["Prometheus (Monitoring)"]:::externalInfra
    Elastic["Elasticsearch/Kibana (Logging)"]:::externalInfra
    DockerInfra["Docker Infra Config"]:::externalInfra
    LocalInfra["Local Infra Config"]:::externalInfra

    %% Connections from Client to API Gateway
    Client -->|"requests"| API_GW

    %% API Gateway forwards requests to services
    API_GW -->|"forwards"| Auth
    API_GW -->|"forwards"| Event
    API_GW -->|"forwards"| Game
    API_GW -->|"forwards"| Background

    %% Authentication provides tokens to other services
    Auth -->|"auth-token"| Event
    Auth -->|"auth-token"| Game
    Auth -->|"auth-token"| Background

    %% Each service uses Shared Building Blocks
    Auth -->|"uses"| Shared
    Event -->|"uses"| Shared
    Game -->|"uses"| Shared
    Background -->|"uses"| Shared

    %% Services communicate with Database (PostgreSQL)
    Auth -->|"db-access"| Postgres
    Event -->|"db-access"| Postgres
    Game -->|"db-access"| Postgres
    Background -->|"db-access"| Postgres

    %% Event and Background services use Redis for PubSub/Cache
    Event -->|"pubsub"| Redis
    Background -->|"pubsub"| Redis

    %% Services send traces, metrics and logs to external monitoring/tracing tools
    Auth -->|"traces"| Zipkin
    Event -->|"traces"| Zipkin
    Game -->|"traces"| Zipkin
    Background -->|"traces"| Zipkin

    Auth -->|"metrics"| Prometheus
    Event -->|"metrics"| Prometheus
    Game -->|"metrics"| Prometheus
    Background -->|"metrics"| Prometheus

    Auth -->|"logs"| Elastic
    Event -->|"logs"| Elastic
    Game -->|"logs"| Elastic
    Background -->|"logs"| Elastic

    %% External Infrastructure configuration linking
    DockerInfra --- Postgres
    DockerInfra --- Redis
    DockerInfra --- Zipkin
    DockerInfra --- Prometheus
    DockerInfra --- Elastic

    DockerInfra --- LocalInfra

    %% Click Events for Components
    click API_GW "https://github.com/minhhuy14/vou-be/tree/main/src/ApiGateway"
    click Auth "https://github.com/minhhuy14/vou-be/tree/main/src/AuthServer"
    click Event "https://github.com/minhhuy14/vou-be/tree/main/src/EventService"
    click Game "https://github.com/minhhuy14/vou-be/tree/main/src/GameService"
    click Background "https://github.com/minhhuy14/vou-be/tree/main/src/BackgroundServiceJobs"
    click Shared "https://github.com/minhhuy14/vou-be/tree/main/src/BuildingBlocks"
    click DockerInfra "https://github.com/minhhuy14/vou-be/tree/main/components/docker"
    click LocalInfra "https://github.com/minhhuy14/vou-be/tree/main/components/localhost"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef shared fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef externalInfra fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef database fill:#FFA07A,stroke:#000,stroke-width:2px;
```
