# arquisoft/wichat_es3a architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-based chat application prototype (“wichat_es3a”) with a React frontend, multiple backend services (Express/Node), a shared MongoDB, and monitoring + CI/CD pipelines.
- The components support user registration, authentication, question generation via an LLM, question history, and a gateway API that fronts all backend services.

##### File Structure Analysis
- Top-level directories correspond to each microservice or component:
- users/authservice & users/userservice
- gateway-api-service & gatewayservice
- llmservice
- historicservice
- questionservice
- webapp (React frontend)
- A docker-compose.yml orchestrates all services (profiles: dev, prod).
- “docs/src” follows the arc42 template, detailing architecture, runtime, deployment views, and decisions.
- CI workflows and Sonar properties at the root indicate automated builds, tests, quality gates, and deploy over SSH.

##### Key Architectural Insights from README
- User service and Auth service share a MongoDB via Mongoose.
- LLM service delegates calls to an external LLM provider (API key).
- Gateway service exposes a single API entrypoint, proxies requests to user/auth/LLM/question/historic services.
- Webapp uses the gateway over HTTP for login, registration, game play, browsing history.
- Monitoring stack (in gatewayservice folder) uses Prometheus + Grafana dashboards.
- CI/CD uses GitHub Actions: runs unit & e2e tests, builds Docker images, pushes to GH Packages, then deploys via SSH.

##### Components
- Frontend (React Webapp)
- API Gateway (gateway-api-service/gatewayservice)
- Auth Service
- User Service
- Question Service
- Historic Service
- LLM Service
- MongoDB Database
- Monitoring Stack (Prometheus, Grafana)
- External LLM Provider API
- CI/CD Pipeline (GitHub Actions)
- Docker Compose Orchestrator
- Deployment Target (Remote VM with Docker)

##### Relationships and Data Flows
- Webapp → HTTP(S) → API Gateway
- Gateway → routed HTTP calls → Auth / User / Question / Historic / LLM services
- Auth & User → read/write → MongoDB
- Question Service may call LLM Service or external LLM API directly
- Historic Service reads from MongoDB (or from Question Service?)
- Monitoring Stack scrapes metrics from each service
- CI/CD pipeline triggers on push or release, runs tests, builds Docker images, pushes them, and SSH-deploys Docker Compose on the remote VM.

##### Architectural Patterns and Principles
- Microservices per bounded context (auth, user, question, historic, llm).
- API Gateway pattern centralizing external access.
- Shared database for related services (auth + user).
- Container-based deployment with Docker Compose profiles (dev/prod).
- Infrastructure as Code via Docker Compose + GitHub Actions.
- Observability via Prometheus + Grafana.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Frontend
    Webapp["React Webapp"]:::frontend
    click Webapp "https://github.com/arquisoft/wichat_es3a/tree/master/webapp/"

    %% CI/CD Pipeline
    Source["Source Repo"]:::ci
    GHA["GitHub Actions"]:::ci
    click GHA "https://github.com/arquisoft/wichat_es3a/blob/master/.github/workflows/build.yml"
    click GHA "https://github.com/arquisoft/wichat_es3a/blob/master/.github/workflows/release.yml"

    %% External Dependency
    ExtLLM["External LLM API"]:::external

    %% Remote VM and Docker Compose boundary
    subgraph "Remote VM"
        subgraph "Docker Compose" 
            direction TB

            %% API Gateway cluster
            subgraph "API Gateway" 
                direction TB
                GWDev["Gateway API (Dev)"]:::api
                Spec["OpenAPI Spec"]:::api
                GWProd["Gateway Service (Prod)"]:::api

                GWDev --> Spec
                click GWDev "https://github.com/arquisoft/wichat_es3a/blob/master/gateway-api-service/gateway-api-service.js"
                click Spec "https://github.com/arquisoft/wichat_es3a/blob/master/gateway-api-service/openapi.yaml"
                click GWProd "https://github.com/arquisoft/wichat_es3a/blob/master/gatewayservice/gateway-service.js"
            end

            %% Microservices cluster
            subgraph "Microservices"
                direction TB

                Auth["Auth Service"]:::micro
                click Auth "https://github.com/arquisoft/wichat_es3a/blob/master/users/authservice/auth-service.js"

                User["User Service"]:::micro
                click User "https://github.com/arquisoft/wichat_es3a/blob/master/users/userservice/user-service.js"

                %% Question Service with internal components
                subgraph "Question Service"
                    direction TB
                    QMain["questionService"]:::micro
                    QGen["questionGeneratorService"]:::micro
                    QSave["questionSaverService"]:::micro
                    QModel["questionModel"]:::micro

                    QMain --> QGen
                    QMain --> QSave
                    QMain --> QModel

                    click QMain "https://github.com/arquisoft/wichat_es3a/blob/master/questionservice/src/service/questionService.js"
                    click QGen "https://github.com/arquisoft/wichat_es3a/blob/master/questionservice/src/service/questionGeneratorService.js"
                    click QSave "https://github.com/arquisoft/wichat_es3a/blob/master/questionservice/src/service/questionSaverService.js"
                    click QModel "https://github.com/arquisoft/wichat_es3a/blob/master/questionservice/src/model/question.js"
                end

                %% Historic Service with model
                subgraph "Historic Service"
                    direction TB
                    HSvc["historicService"]:::micro
                    HModel["questionUserModel"]:::micro

                    HSvc --> HModel

                    click HSvc "https://github.com/arquisoft/wichat_es3a/blob/master/historicservice/historicService.js"
                    click HModel "https://github.com/arquisoft/wichat_es3a/blob/master/historicservice/questionUser.js"
                end

                LS["LLM Service"]:::micro
                click LS "https://github.com/arquisoft/wichat_es3a/blob/master/llmservice/llm-service.js"
            end

            %% Data Layer
            MDB["MongoDB"]:::db

            %% Monitoring Stack
            Prom["Prometheus"]:::monitoring
            Graf["Grafana"]:::monitoring
            click Prom "https://github.com/arquisoft/wichat_es3a/tree/master/gatewayservice/monitoring/"
        end
    end

    %% CI/CD flow
    Source --> GHA -->|"build & deploy"| Docker[("Docker Compose")]:::docker

    %% Frontend to API Gateway
    Webapp -->|"HTTP(S)"| GWProd

    %% Gateway to services
    GWProd -->|"auth routes"| Auth
    GWProd -->|"user routes"| User
    GWProd -->|"question routes"| QMain
    GWProd -->|"historic routes"| HSvc
    GWProd -->|"llm routes"| LS

    %% Services data access
    Auth -->|"read/write"| MDB
    User -->|"read/write"| MDB
    HSvc -->|"read"| MDB

    %% Question Service calling LLM
    QMain -->|"internal call"| LS
    LS -->|"API key"| ExtLLM

    %% Monitoring scrapes
    Prom --> GWProd
    Prom --> Auth
    Prom --> User
    Prom --> QMain
    Prom --> HSvc
    Prom --> LS
    Graf --> Prom

    %% Deployment binds Docker Compose
    GHA -->|"deploy"| Docker

    %% Styles
    classDef frontend fill:#D6E9FF,stroke:#2B6CB0,color:#2B6CB0
    classDef api fill:#D4F5D4,stroke:#2F855A,color:#2F855A
    classDef micro fill:#FFE4B3,stroke:#DD6B20,color:#DD6B20
    classDef db fill:#FFF5F5,stroke:#C53030,color:#C53030,stroke-dasharray: 5 5
    classDef monitoring fill:#F3E8FF,stroke:#805AD5,color:#805AD5
    classDef external fill:#F0FFF4,stroke:#38A169,color:#38A169,stroke-dasharray: 5 5
    classDef ci fill:#EDF2F7,stroke:#4A5568,color:#4A5568
    classDef docker fill:#E6FFFA,stroke:#319795,color:#319795
```
