# arquisoft/wichat_es5b architecture

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

- Interactive diagram: https://gitdiagram.com/arquisoft/wichat_es5b
- Repository: https://github.com/arquisoft/wichat_es5b

## Overview

##### Project Overview and Purpose
- The project is a full-stack microservices application named “wichat_es5b”. It is structured as a set of small, independently deployed services (all built with Express) that together form the application.
- The primary purpose is to offer a chat/game web application with authentication, user management, game logic, and interactions with an external language model (LLM) and Wikidata resources. The front-end (a React-based WebApp) interacts with the backend services via a public gateway.

##### Analyzing the File Structure
- Several top-level directories represent individual microservices:
- gameservice (handles game logic and question management)
- gatewayservice (acts as the entry point, routing public requests)
- llmservice (manages communication with the language model via API keys)
- statsservice (handles usage statistics and history/ranking data)
- users (which is subdivided into authservice and userservice — authentication and user management)
- webapp (the front-end React application that users interact with)
- wikidataservice (fetches question-related data from Wikidata)
- Common files include Dockerfiles and .dockerignore in every service, indicating containerized deployment.
- The presence of docs (with architecture and deployment files) and GitHub workflows (in .github/workflows) implies that CI/CD and automated deployments (via GitHub Actions and SSH) are essential parts of the ecosystem.

##### Identifying the Main System Components
a. Frontend:
- Webapp: A React-based UI that provides the client interface to users.
b. API Gateway:
- Gateway Service: A central proxy exposed to clients; it routes REST API calls to the appropriate back-end microservices.
c. Backend Microservices:
- User Service: Manages user data (sharing MongoDB with auth and stats services).
- Auth Service: Manages authentication.
- Stats Service: Manages user history and global ranking.
- Game Service: Handles game logic, question management, and game progression.
- LLM Service: Communicates with the external LLM API using configured API keys.
- Wikidata Service: Retrieves question-related content from external Wikidata sources.
d. Database:
- Shared MongoDB instance for services (User, Auth, Stats) as described in the README.
e. External/Third-party Integrations:
- LLM Provider (via externally configured API keys)
- Wikidata as a data source.
f. CI/CD and Deployment:
- GitHub Actions workflows for testing, building, pushing Docker images, and automated deployment via SSH.
- Docker Compose file (docker-compose.yml) orchestrates the containers during both development and production deployments.

##### Architectural Patterns and Technology Highlights
- Microservices Architecture: Each service is self-contained and communicates (likely using REST over HTTP) with the gateway service.
- Containerization: All services include Dockerfiles, so Docker is a key technology along with docker-compose for coordination.
- CI/CD Pipeline: GitHub Actions not only runs unit and e2e tests before builds but also manages deployments.
- Shared Database: Some services (User, Auth, Stats) use MongoDB (via Mongoose) as highlighted in the README.
- API Gateway Pattern: The gateway service abstracts and secures access to the microservices.
- External Communication: LLM configuration and Wikidata interactions are clearly separable concerns.

##### Final Detailed Checklist
- Shared database and external API endpoints.
- If applicable, denote Docker container boundaries and CI/CD flow to emphasize deployment approaches.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        A["WebApp (React Frontend)"] 
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        B["Gateway Service (API Gateway)"] 
    end

    %% Microservices Layer
    subgraph "Microservices Layer"
        C["Auth Service"] 
        D["User Service"] 
        E["Stats Service"] 
        F["Game Service"] 
        G["LLM Service"] 
        H["Wikidata Service"] 
    end

    %% Data Storage Layer
    subgraph "Data Storage Layer"
        I[(Shared MongoDB)]
    end

    %% External Integrations
    subgraph "External Integrations"
        J["LLM Provider"]
        K["Wikidata"]
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        L["GitHub Actions"]
        M["Docker Compose"]
    end

    %% Connections: Presentation to API Gateway
    A -->|"REST_requests"| B

    %% API Gateway routes to Microservices
    B -->|"routes"| C
    B -->|"routes"| D
    B -->|"routes"| E
    B -->|"routes"| F
    B -->|"routes"| G
    B -->|"routes"| H

    %% Microservices interactions with Database
    C -->|"uses"| I
    D -->|"uses"| I
    E -->|"uses"| I

    %% External API calls
    G -->|"calls"| J
    H -->|"fetches"| K

    %% CI/CD pipeline deployment flow
    L -->|"triggers"| M
    M -->|"deploys"| A
    M -->|"deploys"| B
    M -->|"deploys"| C
    M -->|"deploys"| D
    M -->|"deploys"| E
    M -->|"deploys"| F
    M -->|"deploys"| G
    M -->|"deploys"| H

    %% Styling Classes
    class A frontend;
    class B gateway;
    class C,D,E,F,G,H microservice;
    class I database;
    class J,K external;
    class L,M cicd;

    %% Class Definitions
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef gateway fill:#ffc107,stroke:#333,stroke-width:2px;
    classDef microservice fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#f5c6cb,stroke:#333,stroke-width:2px;
    classDef cicd fill:#d1ecf1,stroke:#333,stroke-width:2px,stroke-dasharray: 2 2;

    %% Click Events
    click A "https://github.com/arquisoft/wichat_es5b/tree/master/webapp/"
    click B "https://github.com/arquisoft/wichat_es5b/tree/master/gatewayservice/"
    click F "https://github.com/arquisoft/wichat_es5b/tree/master/gameservice/"
    click E "https://github.com/arquisoft/wichat_es5b/tree/master/statsservice/"
    click G "https://github.com/arquisoft/wichat_es5b/tree/master/llmservice/"
    click H "https://github.com/arquisoft/wichat_es5b/tree/master/wikidataservice/"
    click C "https://github.com/arquisoft/wichat_es5b/tree/master/users/authservice/"
    click D "https://github.com/arquisoft/wichat_es5b/tree/master/users/userservice/"
    click L "https://github.com/arquisoft/wichat_es5b/tree/master/.github/workflows/"
    click M "https://github.com/arquisoft/wichat_es5b/blob/master/docker-compose.yml"
```
