# wenuanhappy/ai-museum-studio architecture

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

- Interactive diagram: https://gitdiagram.com/wenuanhappy/ai-museum-studio
- Repository: https://github.com/wenuanhappy/ai-museum-studio

## Overview

AI Museum Studio is a browser-based 3D learning museum about AI history, with optional accounts and real-time shared visitor avatars. The primary visitor flow is to enter the museum and explore historical exhibits; authenticated visitors can also register or sign in, while connected visitors share presence through WebSocket rooms. The README documents first-person navigation, collision limits, and 20+ milestones, but their implementation details are not included in the sampled source, so those internals are represented at the museum-page level.

Main entry points: [`backend/spring/src/main/java/com/aimuseum/museum/MuseumPresenceHandler.java`](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/museum/MuseumPresenceHandler.java) (Presence handler), [`frontend/src/app/app.routes.ts`](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/app.routes.ts) (App routes), [`backend/spring/src/main/java/com/aimuseum/auth/AuthController.java`](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AuthController.java) (Auth API), [`backend/spring/src/main/java/com/aimuseum/auth/AppUserRepository.java`](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AppUserRepository.java) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Museum experience"]
  node_routes["App routes<br/>[app.routes.ts]"]
  node_museum["3D museum"]
  node_home["Home page"]
end

subgraph group_identity["User identity"]
  node_authpage["Auth page"]
  node_authservice["Auth service<br/>[auth.service.ts]"]
  node_api["API client"]
  node_authcontroller["Auth API"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_userdetails["User lookup"]
end

subgraph group_presence["Live presence"]
  node_presencehandler["Presence handler"]
  node_websocket(("WebSocket clients"))
end

subgraph group_backend["Backend services"]
  node_users[("User repository")]
  node_health["Health endpoint"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens app"| node_routes
node_routes -->|"routes home"| node_home
node_routes -->|"routes login"| node_authpage
node_routes -->|"routes museum"| node_museum
node_authpage -->|"submits credentials"| node_authservice
node_authservice -->|"sends requests"| node_api
node_api -->|"HTTP requests"| node_authcontroller
node_authcontroller -->|"reads and saves"| node_users
node_authcontroller -->|"issues tokens"| node_jwt
node_userdetails -->|"loads account"| node_users
node_presencehandler -->|"validates token"| node_jwt
node_presencehandler -->|"looks up visitor"| node_users
node_museum -.->|"WebSocket presence"| node_presencehandler
node_websocket -->|"connects and sends poses"| node_presencehandler
node_presencehandler -->|"broadcasts room state"| node_websocket
node_visitor -->|"checks service"| node_health

click node_routes "https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/app.routes.ts"
click node_museum "https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/modes/ai-museum/ai-museum-page.component.ts"
click node_home "https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/shell/home/home-page.component.ts"
click node_authpage "https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/core/auth/auth-page.component.ts"
click node_authservice "https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/core/auth/auth.service.ts"
click node_api "https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/core/api/api-client.service.ts"
click node_authcontroller "https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AuthController.java"
click node_jwt "https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/JwtService.java"
click node_userdetails "https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AppUserDetailsService.java"
click node_users "https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AppUserRepository.java"
click node_presencehandler "https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/museum/MuseumPresenceHandler.java"
click node_health "https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/common/HealthController.java"

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_routes,node_museum,node_home toneBlue
class node_authpage,node_authservice,node_api,node_authcontroller,node_jwt,node_userdetails toneAmber
class node_presencehandler,node_websocket toneMint
class node_users,node_health toneRose
class node_visitor toneIndigo
```

## Components

### Museum experience

- [App routes](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/app.routes.ts): `frontend/src/app/app.routes.ts`
- [3D museum](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/modes/ai-museum/ai-museum-page.component.ts): `frontend/src/app/modes/ai-museum/ai-museum-page.component.ts`
- [Home page](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/shell/home/home-page.component.ts): `frontend/src/app/shell/home/home-page.component.ts`

### User identity

- [Auth page](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/core/auth/auth-page.component.ts): `frontend/src/app/core/auth/auth-page.component.ts`
- [Auth service](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/core/auth/auth.service.ts): `frontend/src/app/core/auth/auth.service.ts`
- [API client](https://github.com/wenuanhappy/ai-museum-studio/blob/main/frontend/src/app/core/api/api-client.service.ts): `frontend/src/app/core/api/api-client.service.ts`
- [Auth API](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AuthController.java): `backend/spring/src/main/java/com/aimuseum/auth/AuthController.java`
- [JWT service](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/JwtService.java): `backend/spring/src/main/java/com/aimuseum/auth/JwtService.java`
- [User lookup](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AppUserDetailsService.java): `backend/spring/src/main/java/com/aimuseum/auth/AppUserDetailsService.java`

### Live presence

- [Presence handler](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/museum/MuseumPresenceHandler.java): `backend/spring/src/main/java/com/aimuseum/museum/MuseumPresenceHandler.java`
- **WebSocket clients**

### Backend services

- [User repository](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/auth/AppUserRepository.java): `backend/spring/src/main/java/com/aimuseum/auth/AppUserRepository.java`
- [Health endpoint](https://github.com/wenuanhappy/ai-museum-studio/blob/main/backend/spring/src/main/java/com/aimuseum/common/HealthController.java): `backend/spring/src/main/java/com/aimuseum/common/HealthController.java`

### Other components

- **Visitor**

## Connections

- Visitor → App routes: opens app
- App routes → Home page: routes home
- App routes → Auth page: routes login
- App routes → 3D museum: routes museum
- Auth page → Auth service: submits credentials
- Auth service → API client: sends requests
- API client → Auth API: HTTP requests
- Auth API → User repository: reads and saves
- Auth API → JWT service: issues tokens
- User lookup → User repository: loads account
- Presence handler → JWT service: validates token
- Presence handler → User repository: looks up visitor
- 3D museum → Presence handler: WebSocket presence
- WebSocket clients → Presence handler: connects and sends poses
- Presence handler → WebSocket clients: broadcasts room state
- Visitor → Health endpoint: checks service