# jxuan083/graduation-project architecture

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

- Interactive diagram: https://gitdiagram.com/jxuan083/graduation-project
- Repository: https://github.com/jxuan083/graduation-project

## Overview

Phubbing Anchor is a bilingual gathering-focus web app, also packaged as a native shell. The main user flow is: a host creates a room, friends join, participants perform a synchronized focus ritual, and the room’s live session tracks distractions before ending in a summary. The app also supports group Q&A and Taboo games, meeting records and photos, social features, and shared group pets. The graph reflects README-documented capabilities and indexed source references; several view and backend implementations were not excerpted, so their internal call paths are not inferred.

Main entry points: [`backend/main.py`](https://github.com/jxuan083/graduation-project/blob/main/backend/main.py) (FastAPI service), [`frontend/core/api.js`](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/api.js) (REST API client), [`frontend/core/ws.js`](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/ws.js) (Room WebSocket), [`frontend/main.js`](https://github.com/jxuan083/graduation-project/blob/main/frontend/main.js) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["App bootstrap<br/>[main.js]"]
  node_router["View router<br/>[router.js]"]
  node_i18n["Bilingual UI<br/>[i18n.js]"]
  node_api_client["REST API client<br/>[api.js]"]
end

subgraph group_session["Gathering session"]
  node_room_views["Room views<br/>[host-room.js]"]
  node_sync["Sync ritual<br/>[sync-ritual.js]"]
  node_focus["Focus session<br/>[focus.js]"]
  node_ws_client["Room WebSocket<br/>[ws.js]"]
  node_ws_handlers["Session message handlers<br/>[wsHandlers.js]"]
  node_games["Group games<br/>[qa-game.js]"]
  node_taboo["Taboo game logic<br/>[controller.js]"]
  node_meeting_views["Meeting records<br/>[meetings.js]"]
  node_photos["Meeting photos<br/>[controller.js]"]
end

subgraph group_community["Community features"]
  node_friends["Friend system<br/>[controller.js]"]
  node_groups["Group management<br/>[controller.js]"]
  node_pets["Shared pets<br/>[pet-tamagotchi.js]"]
  node_leaderboard["Weekly leaderboard<br/>[controller.js]"]
end

subgraph group_server["Backend services"]
  node_backend["FastAPI service<br/>[main.py]"]
  node_scoring["Scoring logic<br/>[scoring.py]"]
  node_intent["Intent analysis<br/>[intent.py]"]
  node_llm["LLM integration<br/>[llm.py]"]
  node_pet_logic["Pet state logic<br/>[pet_logic.py]"]
end

subgraph group_infra["Identity and storage"]
  node_firebase[("Firebase services")]
  node_cloud_storage[("Firebase file storage")]
end

node_person(("Participant"))

node_person -->|"uses"| node_app
node_app -->|"initializes"| node_router
node_app -->|"registers"| node_ws_handlers
node_app -->|"loads"| node_api_client
node_app -.->|"initializes"| node_i18n
node_router -.->|"routes"| node_room_views
node_room_views -.->|"connects"| node_ws_client
node_person -->|"joins"| node_sync
node_sync -.->|"sends actions"| node_ws_client
node_ws_client -->|"opens room socket"| node_backend
node_backend -->|"sends events"| node_ws_client
node_ws_client -->|"dispatches messages"| node_ws_handlers
node_ws_handlers -->|"updates session view"| node_focus
node_ws_handlers -->|"updates ritual view"| node_sync
node_person -->|"plays"| node_games
node_person -->|"plays"| node_taboo
node_taboo -->|"sends game actions"| node_ws_client
node_person -->|"reviews meetings"| node_meeting_views
node_meeting_views -.->|"manages photos"| node_photos
node_photos -->|"fetches photos"| node_api_client
node_person -->|"manages friends"| node_friends
node_friends -->|"requests data"| node_api_client
node_person -->|"manages groups"| node_groups
node_person -->|"tends pet"| node_pets
node_person -->|"views rankings"| node_leaderboard
node_groups -.->|"requests data"| node_api_client
node_pets -.->|"requests data"| node_api_client
node_leaderboard -.->|"requests data"| node_api_client
node_api_client -->|"sends REST requests"| node_backend
node_backend -->|"reads and writes"| node_firebase
node_backend -->|"stores files"| node_cloud_storage
node_backend -->|"uses scoring"| node_scoring
node_backend -->|"uses analysis"| node_intent
node_backend -->|"uses LLM"| node_llm
node_backend -->|"uses pet logic"| node_pet_logic

click node_app "https://github.com/jxuan083/graduation-project/blob/main/frontend/main.js"
click node_router "https://github.com/jxuan083/graduation-project/blob/main/frontend/core/router.js"
click node_i18n "https://github.com/jxuan083/graduation-project/blob/main/frontend/core/i18n.js"
click node_room_views "https://github.com/jxuan083/graduation-project/blob/main/frontend/views/host-room/host-room.js"
click node_sync "https://github.com/jxuan083/graduation-project/blob/main/frontend/views/sync-ritual/sync-ritual.js"
click node_focus "https://github.com/jxuan083/graduation-project/blob/main/frontend/views/focus/focus.js"
click node_ws_client "https://github.com/jxuan083/graduation-project/blob/main/frontend/core/ws.js"
click node_ws_handlers "https://github.com/jxuan083/graduation-project/blob/main/frontend/core/wsHandlers.js"
click node_games "https://github.com/jxuan083/graduation-project/blob/main/frontend/views/qa-game/qa-game.js"
click node_taboo "https://github.com/jxuan083/graduation-project/blob/main/frontend/features/taboo/controller.js"
click node_meeting_views "https://github.com/jxuan083/graduation-project/blob/main/frontend/views/meetings/meetings.js"
click node_photos "https://github.com/jxuan083/graduation-project/blob/main/frontend/features/photos/controller.js"
click node_friends "https://github.com/jxuan083/graduation-project/blob/main/frontend/features/friends/controller.js"
click node_groups "https://github.com/jxuan083/graduation-project/blob/main/frontend/features/groups/controller.js"
click node_pets "https://github.com/jxuan083/graduation-project/blob/main/frontend/views/pet-tamagotchi/pet-tamagotchi.js"
click node_leaderboard "https://github.com/jxuan083/graduation-project/blob/main/frontend/features/leaderboard/controller.js"
click node_api_client "https://github.com/jxuan083/graduation-project/blob/main/frontend/core/api.js"
click node_backend "https://github.com/jxuan083/graduation-project/blob/main/backend/main.py"
click node_scoring "https://github.com/jxuan083/graduation-project/blob/main/backend/scoring.py"
click node_intent "https://github.com/jxuan083/graduation-project/blob/main/backend/intent.py"
click node_llm "https://github.com/jxuan083/graduation-project/blob/main/backend/llm.py"
click node_pet_logic "https://github.com/jxuan083/graduation-project/blob/main/backend/pet_logic.py"

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_app,node_router,node_i18n,node_api_client toneBlue
class node_room_views,node_sync,node_focus,node_ws_client,node_ws_handlers,node_games,node_taboo,node_meeting_views,node_photos toneAmber
class node_friends,node_groups,node_pets,node_leaderboard toneMint
class node_backend,node_scoring,node_intent,node_llm,node_pet_logic toneRose
class node_firebase,node_cloud_storage,node_person toneIndigo
```

## Components

### Client experience

- [App bootstrap](https://github.com/jxuan083/graduation-project/blob/main/frontend/main.js): `frontend/main.js`
- [View router](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/router.js): `frontend/core/router.js`
- [Bilingual UI](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/i18n.js): `frontend/core/i18n.js`
- [REST API client](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/api.js): `frontend/core/api.js`

### Gathering session

- [Room views](https://github.com/jxuan083/graduation-project/blob/main/frontend/views/host-room/host-room.js): `frontend/views/host-room/host-room.js`
- [Sync ritual](https://github.com/jxuan083/graduation-project/blob/main/frontend/views/sync-ritual/sync-ritual.js): `frontend/views/sync-ritual/sync-ritual.js`
- [Focus session](https://github.com/jxuan083/graduation-project/blob/main/frontend/views/focus/focus.js): `frontend/views/focus/focus.js`
- [Room WebSocket](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/ws.js): `frontend/core/ws.js`
- [Session message handlers](https://github.com/jxuan083/graduation-project/blob/main/frontend/core/wsHandlers.js): `frontend/core/wsHandlers.js`
- [Group games](https://github.com/jxuan083/graduation-project/blob/main/frontend/views/qa-game/qa-game.js): `frontend/views/qa-game/qa-game.js`
- [Taboo game logic](https://github.com/jxuan083/graduation-project/blob/main/frontend/features/taboo/controller.js): `frontend/features/taboo/controller.js`
- [Meeting records](https://github.com/jxuan083/graduation-project/blob/main/frontend/views/meetings/meetings.js): `frontend/views/meetings/meetings.js`
- [Meeting photos](https://github.com/jxuan083/graduation-project/blob/main/frontend/features/photos/controller.js): `frontend/features/photos/controller.js`

### Community features

- [Friend system](https://github.com/jxuan083/graduation-project/blob/main/frontend/features/friends/controller.js): `frontend/features/friends/controller.js`
- [Group management](https://github.com/jxuan083/graduation-project/blob/main/frontend/features/groups/controller.js): `frontend/features/groups/controller.js`
- [Shared pets](https://github.com/jxuan083/graduation-project/blob/main/frontend/views/pet-tamagotchi/pet-tamagotchi.js): `frontend/views/pet-tamagotchi/pet-tamagotchi.js`
- [Weekly leaderboard](https://github.com/jxuan083/graduation-project/blob/main/frontend/features/leaderboard/controller.js): `frontend/features/leaderboard/controller.js`

### Backend services

- [FastAPI service](https://github.com/jxuan083/graduation-project/blob/main/backend/main.py): `backend/main.py`
- [Scoring logic](https://github.com/jxuan083/graduation-project/blob/main/backend/scoring.py): `backend/scoring.py`
- [Intent analysis](https://github.com/jxuan083/graduation-project/blob/main/backend/intent.py): `backend/intent.py`
- [LLM integration](https://github.com/jxuan083/graduation-project/blob/main/backend/llm.py): `backend/llm.py`
- [Pet state logic](https://github.com/jxuan083/graduation-project/blob/main/backend/pet_logic.py): `backend/pet_logic.py`

### Identity and storage

- **Firebase services**
- **Firebase file storage**

### Other components

- **Participant**

## Connections

- Participant → App bootstrap: uses (evidence: `README.md`)
- App bootstrap → View router: initializes (evidence: `frontend/main.js`)
- App bootstrap → Session message handlers: registers (evidence: `frontend/main.js`)
- App bootstrap → REST API client: loads (evidence: `frontend/main.js`)
- App bootstrap → Bilingual UI: initializes
- View router → Room views: routes
- Room views → Room WebSocket: connects
- Participant → Sync ritual: joins (evidence: `README.md`)
- Sync ritual → Room WebSocket: sends actions
- Room WebSocket → FastAPI service: opens room socket (evidence: `README.md`)
- FastAPI service → Room WebSocket: sends events (evidence: `README.md`)
- Room WebSocket → Session message handlers: dispatches messages (evidence: `frontend/core/ws.js`)
- Session message handlers → Focus session: updates session view (evidence: `frontend/core/wsHandlers.js`)
- Session message handlers → Sync ritual: updates ritual view (evidence: `frontend/core/wsHandlers.js`)
- Participant → Group games: plays (evidence: `README.md`)
- Participant → Taboo game logic: plays (evidence: `README.md`)
- Taboo game logic → Room WebSocket: sends game actions (evidence: `frontend/features/taboo/controller.js`)
- Participant → Meeting records: reviews meetings (evidence: `README.md`)
- Meeting records → Meeting photos: manages photos
- Meeting photos → REST API client: fetches photos (evidence: `frontend/features/photos/controller.js`)
- Participant → Friend system: manages friends (evidence: `README.md`)
- Friend system → REST API client: requests data (evidence: `frontend/features/friends/controller.js`)
- Participant → Group management: manages groups (evidence: `README.md`)
- Participant → Shared pets: tends pet (evidence: `README.md`)
- Participant → Weekly leaderboard: views rankings (evidence: `README.md`)
- Group management → REST API client: requests data (evidence: `frontend/features/groups/controller.js`)
- Shared pets → REST API client: requests data (evidence: `frontend/views/pet-tamagotchi/pet-tamagotchi.js`)
- Weekly leaderboard → REST API client: requests data (evidence: `frontend/features/leaderboard/controller.js`)
- REST API client → FastAPI service: sends REST requests (evidence: `README.md`)
- FastAPI service → Firebase services: reads and writes (evidence: `README.md`)
- FastAPI service → Firebase file storage: stores files (evidence: `README.md`)
- FastAPI service → Scoring logic: uses scoring (evidence: `backend/main.py`)
- FastAPI service → Intent analysis: uses analysis (evidence: `backend/main.py`)
- FastAPI service → LLM integration: uses LLM (evidence: `backend/main.py`)
- FastAPI service → Pet state logic: uses pet logic (evidence: `backend/main.py`)
