# piipi-inc/santa_project architecture

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

## Overview

Santa game-app lets users authenticate, create or join a lobby, see its participants, start or restart a randomized gift exchange, and retrieve their assigned recipient’s preferences. The React/MobX frontend selects screens and manages user and lobby state through an API client; the FastAPI backend handles authentication and game operations backed by PostgreSQL, with lobby WebSocket broadcasts. The graph includes documented event and user API branches, though their endpoint implementations were not sampled; frontend-to-backend links are shown as unverified because the excerpts do not establish their wiring.

Main entry points: [`frontend/src/components/ScreenSwitch/index.tsx`](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/ScreenSwitch/index.tsx) (Screen router), [`backend/src/api/v1/__init__.py`](https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/__init__.py) (Versioned router), [`frontend/src/store/Lobbies/index.ts`](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/Lobbies/index.ts) (Lobby state), [`frontend/src/store/index.ts`](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/index.ts) (Root store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_screens["Screen router<br/>[index.tsx]"]
  node_auth_ui["Authentication UI<br/>[index.tsx]"]
  node_lobby_ui["Lobby view<br/>[index.tsx]"]
  node_main_ui["Lobby browsing<br/>[index.tsx]"]
  node_story["Storytelling<br/>[index.tsx]"]
  node_preferences["Preferences<br/>[index.tsx]"]
end

subgraph group_state["Client state and API"]
  node_root_store["Root store<br/>[index.ts]"]
  node_user_store["User state<br/>[index.ts]"]
  node_lobbies_store["Lobby state<br/>[index.ts]"]
  node_screen_store["Screen state<br/>[index.ts]"]
  node_api_client["API client<br/>[index.ts]"]
  node_api_types["API data types<br/>[types.ts]"]
  node_api_mocks["API mocks<br/>[mocks.ts]"]
end

subgraph group_backend["Backend API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_router["Versioned router<br/>[__init__.py]"]
  node_auth_endpoint["Auth endpoints<br/>[auth.py]"]
  node_lobby_endpoint["Lobby endpoints<br/>[lobbies.py]"]
  node_events_endpoint["Event endpoints<br/>[events.py]"]
  node_users_endpoint["User endpoints<br/>[users.py]"]
end

subgraph group_domain["Game domain and storage"]
  node_auth_service["Auth manager"]
  node_lobby_models["Lobby participants<br/>[participant.py]"]
  node_user_model["User model<br/>[user.py]"]
  node_event_model["Event model<br/>[event.py]"]
  node_database["Database sessions<br/>[database.py]"]
end

node_player(("Player"))
node_postgres[("PostgreSQL")]

node_player -->|"uses"| node_app
node_app -->|"renders"| node_screens
node_app -->|"initializes"| node_root_store
node_screens -.->|"selects"| node_auth_ui
node_screens -.->|"selects"| node_lobby_ui
node_screens -.->|"selects"| node_main_ui
node_screens -.->|"selects"| node_story
node_screens -.->|"selects"| node_preferences
node_auth_ui -->|"uses"| node_user_store
node_lobby_ui -->|"uses"| node_lobbies_store
node_main_ui -->|"renders"| node_lobbies_store
node_preferences -.->|"uses"| node_root_store
node_root_store -->|"initializes"| node_user_store
node_root_store -->|"initializes"| node_lobbies_store
node_root_store -->|"changes"| node_screen_store
node_lobbies_store -->|"changes"| node_screen_store
node_user_store -->|"calls"| node_api_client
node_lobbies_store -->|"calls"| node_api_client
node_lobby_ui -->|"starts exchange"| node_lobbies_store
node_api_client -->|"uses"| node_api_types
node_api_client -->|"uses"| node_api_mocks
node_api_client -.->|"requests"| node_api_router
node_api_app -->|"mounts"| node_api_router
node_api_router -->|"registers"| node_auth_endpoint
node_api_router -->|"registers"| node_lobby_endpoint
node_api_router -->|"registers"| node_events_endpoint
node_api_router -->|"registers"| node_users_endpoint
node_auth_endpoint -->|"calls"| node_auth_service
node_auth_endpoint -->|"depends on"| node_database
node_lobby_endpoint -->|"queries"| node_database
node_lobby_endpoint -->|"authenticates"| node_auth_service
node_lobby_endpoint -->|"updates"| node_lobby_models
node_auth_service -->|"queries"| node_database
node_auth_service -->|"creates"| node_user_model
node_database -->|"connects"| node_postgres
node_events_endpoint -.->|"uses"| node_event_model

click node_app "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/App.tsx"
click node_screens "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/ScreenSwitch/index.tsx"
click node_auth_ui "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Authenticate/index.tsx"
click node_lobby_ui "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Lobby/index.tsx"
click node_main_ui "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Main/index.tsx"
click node_story "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/StoryTelling/index.tsx"
click node_preferences "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Preferences/index.tsx"
click node_root_store "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/index.ts"
click node_user_store "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/User/index.ts"
click node_lobbies_store "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/Lobbies/index.ts"
click node_screen_store "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/screen/index.ts"
click node_api_client "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/api/index.ts"
click node_api_types "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/api/types/types.ts"
click node_api_mocks "https://github.com/piipi-inc/santa_project/blob/main/frontend/src/api/mocks.ts"
click node_api_app "https://github.com/piipi-inc/santa_project/blob/main/backend/src/main.py"
click node_api_router "https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/__init__.py"
click node_auth_endpoint "https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/auth.py"
click node_lobby_endpoint "https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/lobbies.py"
click node_events_endpoint "https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/events.py"
click node_users_endpoint "https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/users.py"
click node_auth_service "https://github.com/piipi-inc/santa_project/blob/main/backend/src/services/auth_manager_service.py"
click node_lobby_models "https://github.com/piipi-inc/santa_project/blob/main/backend/src/models/participant.py"
click node_user_model "https://github.com/piipi-inc/santa_project/blob/main/backend/src/models/user.py"
click node_event_model "https://github.com/piipi-inc/santa_project/blob/main/backend/src/models/event.py"
click node_database "https://github.com/piipi-inc/santa_project/blob/main/backend/src/core/database.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_screens,node_auth_ui,node_lobby_ui,node_main_ui,node_story,node_preferences toneBlue
class node_root_store,node_user_store,node_lobbies_store,node_screen_store,node_api_client,node_api_types,node_api_mocks,node_postgres toneAmber
class node_api_app,node_api_router,node_auth_endpoint,node_lobby_endpoint,node_events_endpoint,node_users_endpoint toneMint
class node_auth_service,node_lobby_models,node_user_model,node_event_model,node_database toneRose
class node_player toneIndigo
```

## Components

### Frontend experience

- [App shell](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Screen router](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/ScreenSwitch/index.tsx): `frontend/src/components/ScreenSwitch/index.tsx`
- [Authentication UI](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Authenticate/index.tsx): `frontend/src/components/Authenticate/index.tsx`
- [Lobby view](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Lobby/index.tsx): `frontend/src/components/Lobby/index.tsx`
- [Lobby browsing](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Main/index.tsx): `frontend/src/components/Main/index.tsx`
- [Storytelling](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/StoryTelling/index.tsx): `frontend/src/components/StoryTelling/index.tsx`
- [Preferences](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/components/Preferences/index.tsx): `frontend/src/components/Preferences/index.tsx`

### Client state and API

- [Root store](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/index.ts): `frontend/src/store/index.ts`
- [User state](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/User/index.ts): `frontend/src/store/User/index.ts`
- [Lobby state](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/Lobbies/index.ts): `frontend/src/store/Lobbies/index.ts`
- [Screen state](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/store/screen/index.ts): `frontend/src/store/screen/index.ts`
- [API client](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/api/index.ts): `frontend/src/api/index.ts`
- [API data types](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/api/types/types.ts): `frontend/src/api/types/types.ts`
- [API mocks](https://github.com/piipi-inc/santa_project/blob/main/frontend/src/api/mocks.ts): `frontend/src/api/mocks.ts`

### Backend API

- [FastAPI application](https://github.com/piipi-inc/santa_project/blob/main/backend/src/main.py): `backend/src/main.py`
- [Versioned router](https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/__init__.py): `backend/src/api/v1/__init__.py`
- [Auth endpoints](https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/auth.py): `backend/src/api/v1/endpoints/auth.py`
- [Lobby endpoints](https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/lobbies.py): `backend/src/api/v1/endpoints/lobbies.py`
- [Event endpoints](https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/events.py): `backend/src/api/v1/endpoints/events.py`
- [User endpoints](https://github.com/piipi-inc/santa_project/blob/main/backend/src/api/v1/endpoints/users.py): `backend/src/api/v1/endpoints/users.py`

### Game domain and storage

- [Auth manager](https://github.com/piipi-inc/santa_project/blob/main/backend/src/services/auth_manager_service.py): `backend/src/services/auth_manager_service.py`
- [Lobby participants](https://github.com/piipi-inc/santa_project/blob/main/backend/src/models/participant.py): `backend/src/models/participant.py`
- [User model](https://github.com/piipi-inc/santa_project/blob/main/backend/src/models/user.py): `backend/src/models/user.py`
- [Event model](https://github.com/piipi-inc/santa_project/blob/main/backend/src/models/event.py): `backend/src/models/event.py`
- [Database sessions](https://github.com/piipi-inc/santa_project/blob/main/backend/src/core/database.py): `backend/src/core/database.py`

### Other components

- **Player**
- **PostgreSQL**

## Connections

- Player → App shell: uses
- App shell → Screen router: renders (evidence: `frontend/src/App.tsx`)
- App shell → Root store: initializes (evidence: `frontend/src/App.tsx`)
- Screen router → Authentication UI: selects
- Screen router → Lobby view: selects
- Screen router → Lobby browsing: selects
- Screen router → Storytelling: selects
- Screen router → Preferences: selects
- Authentication UI → User state: uses (evidence: `frontend/src/components/Authenticate/index.tsx`)
- Lobby view → Lobby state: uses (evidence: `frontend/src/components/Lobby/index.tsx`)
- Lobby browsing → Lobby state: renders (evidence: `frontend/src/components/Main/index.tsx`)
- Preferences → Root store: uses
- Root store → User state: initializes (evidence: `frontend/src/store/index.ts`)
- Root store → Lobby state: initializes (evidence: `frontend/src/store/index.ts`)
- Root store → Screen state: changes (evidence: `frontend/src/store/index.ts`)
- Lobby state → Screen state: changes (evidence: `frontend/src/store/Lobbies/index.ts`)
- User state → API client: calls (evidence: `frontend/src/store/User/index.ts`)
- Lobby state → API client: calls (evidence: `frontend/src/store/Lobbies/index.ts`)
- Lobby view → Lobby state: starts exchange (evidence: `frontend/src/components/Lobby/index.tsx`)
- API client → API data types: uses (evidence: `frontend/src/api/index.ts`)
- API client → API mocks: uses (evidence: `frontend/src/api/index.ts`)
- API client → Versioned router: requests
- FastAPI application → Versioned router: mounts (evidence: `backend/src/main.py`)
- Versioned router → Auth endpoints: registers (evidence: `backend/src/api/v1/__init__.py`)
- Versioned router → Lobby endpoints: registers (evidence: `backend/src/api/v1/__init__.py`)
- Versioned router → Event endpoints: registers (evidence: `backend/src/api/v1/__init__.py`)
- Versioned router → User endpoints: registers (evidence: `backend/src/api/v1/__init__.py`)
- Auth endpoints → Auth manager: calls (evidence: `backend/src/api/v1/endpoints/auth.py`)
- Auth endpoints → Database sessions: depends on (evidence: `backend/src/api/v1/endpoints/auth.py`)
- Lobby endpoints → Database sessions: queries (evidence: `backend/src/api/v1/endpoints/lobbies.py`)
- Lobby endpoints → Auth manager: authenticates (evidence: `backend/src/api/v1/endpoints/lobbies.py`)
- Lobby endpoints → Lobby participants: updates (evidence: `backend/src/api/v1/endpoints/lobbies.py`)
- Auth manager → Database sessions: queries (evidence: `backend/src/services/auth_manager_service.py`)
- Auth manager → User model: creates (evidence: `backend/src/services/auth_manager_service.py`)
- Database sessions → PostgreSQL: connects (evidence: `backend/src/core/database.py`)
- Event endpoints → Event model: uses
