# jayflux/wordduel architecture

> Architecture diagram of the GitHub repository jayflux/wordduel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jayflux/wordduel
- Repository: https://github.com/jayflux/wordduel

## Overview

Word Duel is a multiplayer Wordle game whose main flow is account login, ELO-based opponent matching, a live two-player game with chat, and rating/leaderboard updates when a match ends. The frontend drives authentication, matchmaking, profile and leaderboard views, and the Socket.IO game session. Login delegates account data to the user service; matchmaking fetches player ELO over gRPC; the game service reports completed matches to the user service, which coordinates profile and leaderboard updates. The README documents Nginx routing and login failover; unsampled configuration prevents tracing every route in detail.

Main entry points: [`frontend/app.js`](https://github.com/jayflux/wordduel/blob/main/frontend/app.js) (Game Frontend), [`user-service/index.js`](https://github.com/jayflux/wordduel/blob/main/user-service/index.js) (User Service), [`matchmaking-service/index.js`](https://github.com/jayflux/wordduel/blob/main/matchmaking-service/index.js) (Matchmaking Service), [`chat-service/index.js`](https://github.com/jayflux/wordduel/blob/main/chat-service/index.js) (Chat And Game)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Player Client"]
  node_frontend["Game Frontend<br/>[app.js]"]
end

subgraph group_gateway["Gateway And Auth"]
  node_nginx["Nginx Gateway<br/>[nginx.conf]"]
  node_login["Login Service<br/>[index.js]"]
end

subgraph group_game["Match And Game"]
  node_matchmaking["Matchmaking Service<br/>[index.js]"]
  node_chatgame["Chat And Game<br/>[index.js]"]
end

subgraph group_accounts["Profiles And Ratings"]
  node_user["User Service<br/>[index.js]"]
  node_ranking["Ranking Service<br/>[index.js]"]
end

subgraph group_state["Persistent State"]
  node_postgres[("PostgreSQL Master")]
  node_replica[("PostgreSQL Replica")]
  node_redis[("Redis Leaderboard")]
end

node_player(("Player"))

node_player -->|"plays"| node_frontend
node_frontend -->|"loads and routes"| node_nginx
node_nginx -->|"proxies auth"| node_login
node_login -->|"creates or reads account"| node_user
node_frontend -->|"joins or leaves queue"| node_matchmaking
node_matchmaking -->|"requests ELO"| node_user
node_matchmaking -->|"returns opponent"| node_frontend
node_frontend -->|"sends game events"| node_chatgame
node_chatgame -->|"broadcasts game and chat"| node_frontend
node_chatgame -->|"submits match result"| node_user
node_user -->|"updates ratings"| node_ranking
node_frontend -->|"requests profile"| node_user
node_frontend -->|"requests leaderboard"| node_ranking
node_user -->|"writes profiles and ratings"| node_postgres
node_user -->|"reads profiles and ELO"| node_replica
node_ranking -->|"reads and writes scores"| node_redis

click node_frontend "https://github.com/jayflux/wordduel/blob/main/frontend/app.js"
click node_nginx "https://github.com/jayflux/wordduel/blob/main/nginx.conf"
click node_login "https://github.com/jayflux/wordduel/blob/main/login-service/index.js"
click node_matchmaking "https://github.com/jayflux/wordduel/blob/main/matchmaking-service/index.js"
click node_chatgame "https://github.com/jayflux/wordduel/blob/main/chat-service/index.js"
click node_user "https://github.com/jayflux/wordduel/blob/main/user-service/index.js"
click node_ranking "https://github.com/jayflux/wordduel/blob/main/ranking-service/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend toneBlue
class node_nginx,node_login toneAmber
class node_matchmaking,node_chatgame toneMint
class node_user,node_ranking toneRose
class node_postgres,node_replica,node_redis,node_player toneIndigo
```

## Components

### Player Client

- [Game Frontend](https://github.com/jayflux/wordduel/blob/main/frontend/app.js): `frontend/app.js`

### Gateway And Auth

- [Nginx Gateway](https://github.com/jayflux/wordduel/blob/main/nginx.conf): `nginx.conf`
- [Login Service](https://github.com/jayflux/wordduel/blob/main/login-service/index.js): `login-service/index.js`

### Match And Game

- [Matchmaking Service](https://github.com/jayflux/wordduel/blob/main/matchmaking-service/index.js): `matchmaking-service/index.js`
- [Chat And Game](https://github.com/jayflux/wordduel/blob/main/chat-service/index.js): `chat-service/index.js`

### Profiles And Ratings

- [User Service](https://github.com/jayflux/wordduel/blob/main/user-service/index.js): `user-service/index.js`
- [Ranking Service](https://github.com/jayflux/wordduel/blob/main/ranking-service/index.js): `ranking-service/index.js`

### Persistent State

- **PostgreSQL Master**
- **PostgreSQL Replica**
- **Redis Leaderboard**

### Other components

- **Player**

## Connections

- Player → Game Frontend: plays
- Game Frontend → Nginx Gateway: loads and routes
- Nginx Gateway → Login Service: proxies auth
- Login Service → User Service: creates or reads account
- Game Frontend → Matchmaking Service: joins or leaves queue
- Matchmaking Service → User Service: requests ELO
- Matchmaking Service → Game Frontend: returns opponent
- Game Frontend → Chat And Game: sends game events
- Chat And Game → Game Frontend: broadcasts game and chat
- Chat And Game → User Service: submits match result
- User Service → Ranking Service: updates ratings
- Game Frontend → User Service: requests profile
- Game Frontend → Ranking Service: requests leaderboard
- User Service → PostgreSQL Master: writes profiles and ratings
- User Service → PostgreSQL Replica: reads profiles and ELO
- Ranking Service → Redis Leaderboard: reads and writes scores