# tungpham42/cotuongchamtop architecture

> Architecture diagram of the GitHub repository tungpham42/cotuongchamtop, 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/tungpham42/cotuongchamtop
- Repository: https://github.com/tungpham42/cotuongchamtop

## Overview

This repository is a Vietnamese Xiangqi web application. Players can find opponents, play in rooms, and use puzzles, tournaments, chat, and AI analysis; the tree also shows account, content, and administration features. The sampled room controller demonstrates room updates, matchmaking, and broadcasts, while the analysis controller calls the engine and AI service. Other capabilities are represented by their named controllers and services, but their internal wiring was not sampled. The README describes Laravel rather than this product, so product capabilities are inferred from the tree and excerpts.

Main entry points: [`config/database.php`](https://github.com/tungpham42/cotuongchamtop/blob/master/config/database.php) (Application database), [`app/Http/Controllers/RoomController.php`](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/RoomController.php) (Room endpoints), [`app/Http/Controllers/Api/ChessAnalysisController.php`](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/Api/ChessAnalysisController.php) (Analysis API), [`app/Http/Controllers/Auth/LoginController.php`](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/Auth/LoginController.php) (Login and identity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web entry"]
  node_room_controller["Room endpoints<br/>[RoomController.php]"]
  node_game_controller["Game endpoints<br/>[GameController.php]"]
  node_puzzle_controller["Puzzle endpoints"]
  node_tournament_controller["Tournament endpoints"]
  node_analysis_controller["Analysis API"]
end

subgraph group_play["Play and community"]
  node_room_service["Room services<br/>[RoomService.php]"]
  node_tournament_service["Tournament services"]
  node_puzzle_service["Puzzle services<br/>[PuzzleService.php]"]
  node_chat["Player chat<br/>[ChatController.php]"]
  node_room_events["Live room events<br/>[RoomUpdated.php]"]
end

subgraph group_accounts["Accounts and content"]
  node_login_controller["Login and identity"]
  node_user_controller["User endpoints<br/>[UserController.php]"]
  node_article_controller["Articles"]
  node_admin["Administration"]
  node_karma_action["Login rewards"]
end

subgraph group_analysis["Analysis engines"]
  node_xiangqi_engine_service["Xiangqi analysis"]
  node_groq_service["AI coach"]
  node_engine_client["Worker pool client"]
  node_engine_worker["Engine worker"]
  node_pikafish_process["Pikafish process"]
end

subgraph group_data["Domain data"]
  node_database[("Application database<br/>[database.php]")]
  node_room_model["Rooms<br/>[Room.php]"]
  node_user_model["Users<br/>[User.php]"]
  node_game_model["Games<br/>[Game.php]"]
  node_puzzle_model["Puzzles<br/>[Puzzle.php]"]
  node_tournament_model["Tournaments<br/>[Tournament.php]"]
end

node_players(("Players"))
node_groq{{"Groq AI service"}}

node_players -->|"request rooms"| node_room_controller
node_players -->|"play games"| node_game_controller
node_players -->|"solve puzzles"| node_puzzle_controller
node_players -->|"enter tournaments"| node_tournament_controller
node_players -->|"request analysis"| node_analysis_controller
node_players -->|"sign in"| node_login_controller
node_players -->|"send messages"| node_chat
node_room_controller -->|"read and save"| node_room_model
node_room_controller -->|"broadcast updates"| node_room_events
node_login_controller -->|"find or create"| node_user_model
node_login_controller -->|"award login"| node_karma_action
node_analysis_controller -->|"analyze position"| node_xiangqi_engine_service
node_analysis_controller -->|"request coaching"| node_groq_service
node_groq_service -.->|"request AI response"| node_groq
node_xiangqi_engine_service -->|"run engine"| node_pikafish_process
node_engine_worker -->|"start and manage"| node_pikafish_process
node_engine_client -->|"send socket requests"| node_engine_worker
node_room_model -->|"persist room state"| node_database
node_user_model -->|"persist accounts"| node_database
node_game_model -->|"persist games"| node_database
node_puzzle_model -->|"persist puzzles"| node_database
node_tournament_model -->|"persist tournaments"| node_database

click node_room_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/RoomController.php"
click node_game_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/GameController.php"
click node_puzzle_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/PuzzleController.php"
click node_tournament_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/TournamentController.php"
click node_analysis_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/Api/ChessAnalysisController.php"
click node_room_service "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/RoomService.php"
click node_tournament_service "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/TournamentService.php"
click node_puzzle_service "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/PuzzleService.php"
click node_chat "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/ChatController.php"
click node_room_events "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Events/RoomUpdated.php"
click node_login_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/Auth/LoginController.php"
click node_user_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/UserController.php"
click node_article_controller "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/ArticleController.php"
click node_admin "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/AdminController.php"
click node_karma_action "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Actions/User/AwardLoginKarmaAction.php"
click node_xiangqi_engine_service "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/XiangqiEngineService.php"
click node_groq_service "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/GroqChessService.php"
click node_engine_client "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/XiangqiEngineClient.php"
click node_engine_worker "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Console/Commands/XiangqiEngineWorkerCommand.php"
click node_pikafish_process "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/Xiangqi/PikafishProcess.php"
click node_database "https://github.com/tungpham42/cotuongchamtop/blob/master/config/database.php"
click node_room_model "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Room.php"
click node_user_model "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/User.php"
click node_game_model "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Game.php"
click node_puzzle_model "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Puzzle.php"
click node_tournament_model "https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Tournament.php"

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_room_controller,node_game_controller,node_puzzle_controller,node_tournament_controller,node_analysis_controller toneBlue
class node_room_service,node_tournament_service,node_puzzle_service,node_chat,node_room_events toneAmber
class node_login_controller,node_user_controller,node_article_controller,node_admin,node_karma_action toneMint
class node_xiangqi_engine_service,node_groq_service,node_engine_client,node_engine_worker,node_pikafish_process toneRose
class node_database,node_room_model,node_user_model,node_game_model,node_puzzle_model,node_tournament_model,node_players,node_groq toneIndigo
```

## Components

### Web entry

- [Room endpoints](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/RoomController.php): `app/Http/Controllers/RoomController.php`
- [Game endpoints](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/GameController.php): `app/Http/Controllers/GameController.php`
- [Puzzle endpoints](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/PuzzleController.php): `app/Http/Controllers/PuzzleController.php`
- [Tournament endpoints](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/TournamentController.php): `app/Http/Controllers/TournamentController.php`
- [Analysis API](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/Api/ChessAnalysisController.php): `app/Http/Controllers/Api/ChessAnalysisController.php`

### Play and community

- [Room services](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/RoomService.php): `app/Services/RoomService.php`
- [Tournament services](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/TournamentService.php): `app/Services/TournamentService.php`
- [Puzzle services](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/PuzzleService.php): `app/Services/PuzzleService.php`
- [Player chat](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/ChatController.php): `app/Http/Controllers/ChatController.php`
- [Live room events](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Events/RoomUpdated.php): `app/Events/RoomUpdated.php`

### Accounts and content

- [Login and identity](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/Auth/LoginController.php): `app/Http/Controllers/Auth/LoginController.php`
- [User endpoints](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/UserController.php): `app/Http/Controllers/UserController.php`
- [Articles](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/ArticleController.php): `app/Http/Controllers/ArticleController.php`
- [Administration](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Http/Controllers/AdminController.php): `app/Http/Controllers/AdminController.php`
- [Login rewards](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Actions/User/AwardLoginKarmaAction.php): `app/Actions/User/AwardLoginKarmaAction.php`

### Analysis engines

- [Xiangqi analysis](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/XiangqiEngineService.php): `app/Services/XiangqiEngineService.php`
- [AI coach](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/GroqChessService.php): `app/Services/GroqChessService.php`
- [Worker pool client](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/XiangqiEngineClient.php): `app/Services/XiangqiEngineClient.php`
- [Engine worker](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Console/Commands/XiangqiEngineWorkerCommand.php): `app/Console/Commands/XiangqiEngineWorkerCommand.php`
- [Pikafish process](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Services/Xiangqi/PikafishProcess.php): `app/Services/Xiangqi/PikafishProcess.php`

### Domain data

- [Application database](https://github.com/tungpham42/cotuongchamtop/blob/master/config/database.php): `config/database.php`
- [Rooms](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Room.php): `app/Models/Room.php`
- [Users](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/User.php): `app/Models/User.php`
- [Games](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Game.php): `app/Models/Game.php`
- [Puzzles](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Puzzle.php): `app/Models/Puzzle.php`
- [Tournaments](https://github.com/tungpham42/cotuongchamtop/blob/master/app/Models/Tournament.php): `app/Models/Tournament.php`

### Other components

- **Players**
- **Groq AI service**

## Connections

- Players → Room endpoints: request rooms
- Players → Game endpoints: play games
- Players → Puzzle endpoints: solve puzzles
- Players → Tournament endpoints: enter tournaments
- Players → Analysis API: request analysis
- Players → Login and identity: sign in
- Players → Player chat: send messages
- Room endpoints → Rooms: read and save
- Room endpoints → Live room events: broadcast updates
- Login and identity → Users: find or create
- Login and identity → Login rewards: award login
- Analysis API → Xiangqi analysis: analyze position
- Analysis API → AI coach: request coaching
- AI coach → Groq AI service: request AI response
- Xiangqi analysis → Pikafish process: run engine
- Engine worker → Pikafish process: start and manage
- Worker pool client → Engine worker: send socket requests
- Rooms → Application database: persist room state
- Users → Application database: persist accounts
- Games → Application database: persist games
- Puzzles → Application database: persist puzzles
- Tournaments → Application database: persist tournaments