# lyihub/ar-mahjong-assistant-preview architecture

> Architecture diagram of the GitHub repository lyihub/ar-mahjong-assistant-preview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lyihub/ar-mahjong-assistant-preview
- Repository: https://github.com/lyihub/ar-mahjong-assistant-preview

## Overview

ARmahjongAssist is an Android/RayNeo client backed by a FastAPI server for local Mahjong recognition, state tracking, and play advice. The main workflow captures a hand image, submits it with a session, detects tiles, updates game state, computes a recommendation, and returns it for display. A separate voice path transcribes audio and interprets game events to update visible-tile state. The README documents these stages; some Android internals and unsampled server implementation details are represented only at documented subsystem level.

Main entry points: [`server/main.py`](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/main.py) (FastAPI Routes), [`app/src/main/java/com/example/ai_assist/MainActivity.kt`](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/MainActivity.kt) (RayNeo App), [`app/src/main/java/com/example/ai_assist/viewmodel/ChatViewModel.kt`](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/viewmodel/ChatViewModel.kt) (Chat ViewModel), [`app/src/main/java/com/example/ai_assist/repository/ChatRepository.kt`](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/repository/ChatRepository.kt) (Chat Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["AR Client"]
  node_glasses["RayNeo App<br/>[MainActivity.kt]"]
  node_viewmodel["Chat ViewModel<br/>[ChatViewModel.kt]"]
  node_repo["Chat Repository<br/>[ChatRepository.kt]"]
  node_api_client["Game API Client<br/>[GameApiService.kt]"]
  node_device["Device Controls"]
  node_audio_rec["Audio Recorder"]
  node_mahjong_map["Tile Mapper<br/>[MahjongMapper.kt]"]
  node_app_models["Session Models<br/>[SessionModels.kt]"]
end

subgraph group_api["Server API"]
  node_server["FastAPI Routes<br/>[main.py]"]
  node_config["Runtime Config<br/>[config.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
  node_history[("Session History<br/>[database.py]")]
end

subgraph group_vision["Tile Vision"]
  node_vision_service["Vision Service<br/>[vision_service.py]"]
  node_yolo["ONNX Detection<br/>[yolo_inference.py]"]
end

subgraph group_game["Game Analysis"]
  node_tracker["State Tracker"]
  node_efficiency["Play Efficiency"]
end

subgraph group_voice["Voice Events"]
  node_stt["Speech Recognition<br/>[stt_service.py]"]
  node_llm["Voice Intent<br/>[llm_service.py]"]
end

node_player(("Player"))
node_local_model["Local ONNX Model<br/>[weights.onnx]"]
node_llm_service["OpenAI-Compatible LLM"]

node_player -->|"operates"| node_glasses
node_glasses -.->|"manages UI"| node_viewmodel
node_viewmodel -.->|"uses"| node_repo
node_repo -.->|"requests"| node_api_client
node_glasses -.->|"reads controls"| node_device
node_glasses -.->|"records audio"| node_audio_rec
node_glasses -->|"uploads hand"| node_server
node_server -->|"detects tiles"| node_vision_service
node_vision_service -->|"runs inference"| node_yolo
node_yolo -.->|"loads model"| node_local_model
node_server -->|"updates state"| node_tracker
node_server -->|"calculates advice"| node_efficiency
node_server -->|"records sessions"| node_history
node_server -->|"formats response"| node_schemas
node_server -->|"returns advice"| node_glasses
node_audio_rec -->|"uploads audio"| node_server
node_server -->|"transcribes audio"| node_stt
node_stt -->|"passes transcript"| node_llm
node_llm -.->|"interprets events"| node_llm_service
node_server -->|"applies events"| node_tracker
node_server -->|"uses settings"| node_config

click node_glasses "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/MainActivity.kt"
click node_viewmodel "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/viewmodel/ChatViewModel.kt"
click node_repo "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/repository/ChatRepository.kt"
click node_api_client "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/service/GameApiService.kt"
click node_device "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/service/RayNeoDeviceManager.kt"
click node_audio_rec "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/utils/RayNeoAudioRecorder.kt"
click node_mahjong_map "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/utils/MahjongMapper.kt"
click node_app_models "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/model/SessionModels.kt"
click node_server "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/main.py"
click node_config "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/config.py"
click node_schemas "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/schemas.py"
click node_history "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/database.py"
click node_vision_service "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/vision_service.py"
click node_yolo "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/yolo_inference.py"
click node_tracker "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/mahjong_state_tracker.py"
click node_efficiency "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/efficiency_engine.py"
click node_stt "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/stt_service.py"
click node_llm "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/llm_service.py"
click node_local_model "https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/models/yolo/weights.onnx"

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_glasses,node_viewmodel,node_repo,node_api_client,node_device,node_audio_rec,node_mahjong_map,node_app_models toneBlue
class node_server,node_config,node_schemas,node_history toneAmber
class node_vision_service,node_yolo toneMint
class node_tracker,node_efficiency toneRose
class node_stt,node_llm,node_player,node_local_model,node_llm_service toneIndigo
```

## Components

### AR Client

- [RayNeo App](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/MainActivity.kt): `app/src/main/java/com/example/ai_assist/MainActivity.kt`
- [Chat ViewModel](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/viewmodel/ChatViewModel.kt): `app/src/main/java/com/example/ai_assist/viewmodel/ChatViewModel.kt`
- [Chat Repository](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/repository/ChatRepository.kt): `app/src/main/java/com/example/ai_assist/repository/ChatRepository.kt`
- [Game API Client](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/service/GameApiService.kt): `app/src/main/java/com/example/ai_assist/service/GameApiService.kt`
- [Device Controls](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/service/RayNeoDeviceManager.kt): `app/src/main/java/com/example/ai_assist/service/RayNeoDeviceManager.kt`
- [Audio Recorder](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/utils/RayNeoAudioRecorder.kt): `app/src/main/java/com/example/ai_assist/utils/RayNeoAudioRecorder.kt`
- [Tile Mapper](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/utils/MahjongMapper.kt): `app/src/main/java/com/example/ai_assist/utils/MahjongMapper.kt`
- [Session Models](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/app/src/main/java/com/example/ai_assist/model/SessionModels.kt): `app/src/main/java/com/example/ai_assist/model/SessionModels.kt`

### Server API

- [FastAPI Routes](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/main.py): `server/main.py`
- [Runtime Config](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/config.py): `server/config.py`
- [API Schemas](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/schemas.py): `server/schemas.py`
- [Session History](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/database.py): `server/database.py`

### Tile Vision

- [Vision Service](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/vision_service.py): `server/vision_service.py`
- [ONNX Detection](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/yolo_inference.py): `server/yolo_inference.py`

### Game Analysis

- [State Tracker](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/mahjong_state_tracker.py): `server/mahjong_state_tracker.py`
- [Play Efficiency](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/efficiency_engine.py): `server/efficiency_engine.py`

### Voice Events

- [Speech Recognition](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/stt_service.py): `server/stt_service.py`
- [Voice Intent](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/llm_service.py): `server/llm_service.py`

### Other components

- **Player**
- [Local ONNX Model](https://github.com/lyihub/ar-mahjong-assistant-preview/blob/main/server/models/yolo/weights.onnx): `server/models/yolo/weights.onnx`
- **OpenAI-Compatible LLM**

## Connections

- Player → RayNeo App: operates (evidence: `README.md`)
- RayNeo App → Chat ViewModel: manages UI
- Chat ViewModel → Chat Repository: uses
- Chat Repository → Game API Client: requests
- RayNeo App → Device Controls: reads controls
- RayNeo App → Audio Recorder: records audio
- RayNeo App → FastAPI Routes: uploads hand (evidence: `README.md`)
- FastAPI Routes → Vision Service: detects tiles (evidence: `server/main.py`)
- Vision Service → ONNX Detection: runs inference (evidence: `server/vision_service.py`)
- ONNX Detection → Local ONNX Model: loads model
- FastAPI Routes → State Tracker: updates state (evidence: `server/main.py`)
- FastAPI Routes → Play Efficiency: calculates advice (evidence: `README.md`)
- FastAPI Routes → Session History: records sessions (evidence: `server/main.py`)
- FastAPI Routes → API Schemas: formats response (evidence: `server/main.py`)
- FastAPI Routes → RayNeo App: returns advice (evidence: `README.md`)
- Audio Recorder → FastAPI Routes: uploads audio (evidence: `README.md`)
- FastAPI Routes → Speech Recognition: transcribes audio (evidence: `README.md`)
- Speech Recognition → Voice Intent: passes transcript (evidence: `README.md`)
- Voice Intent → OpenAI-Compatible LLM: interprets events
- FastAPI Routes → State Tracker: applies events (evidence: `README.md`)
- FastAPI Routes → Runtime Config: uses settings (evidence: `server/main.py`)
