# vishal-shaw20/game-social architecture

> Architecture diagram of the GitHub repository vishal-shaw20/game-social, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishal-shaw20/game-social
- Repository: https://github.com/vishal-shaw20/game-social

## Overview

1. **Overall shape**
   GameSocial is a three-service system: a React frontend, a Node/Express backend, and a Python FastAPI recommendation service (`gamiq`). They are connected by REST, Socket.IO, and shared infrastructure services like MongoDB, PostgreSQL, and Redis.

2. **Frontend boundary**
   The frontend is a Vite-built React SPA. Its main responsibility is presentation and client-side interaction: browsing games, showing profiles/libraries/reviews, and participating in real-time chat. It uses hooks for auth and socket handling, and components are organized around major user-facing areas like search, game pages, social feed, and library views.

3. **Backend as the application hub**
   The Express backend is the main orchestration layer. Route modules separate concerns for auth, profiles, friends, reviews, notifications, search, trending, and game lookup. This service is also where session/auth checks, request limiting, and Steam auto-sync logic are enforced.

4. **Authentication and identity**
   Authentication is multi-provider: Google OAuth, Steam OpenID, and email/password with OTP verification. Passport strategies implement the external login flows, while middleware such as `requireAuth` protects private routes. The backend also supports account linking across providers, which makes the user identity model a central boundary.

5. **Persistent data split**
   MongoDB stores application/user-centric data such as users, reviews, comments, notifications, activities, and Steam libraries. PostgreSQL is used for the game catalog and other query-heavy data, including embeddings and chat-oriented data. This split matters: Mongo backs social/account workflows, while Postgres supports large-scale game search and ML-backed retrieval.

6. **Game discovery pipeline**
   Game discovery is fed by external data sources and scheduled jobs. Cron tasks pull trending data from SteamSpy and game data from RAWG, while helper utilities map RAWG IDs to Steam IDs and normalize game metadata. The backend exposes this merged catalog through search, trending, and game lookup routes.

7. **Library sync and ownership**
   Steam library sync is a first-class feature, not an afterthought. On login or via the Steam auto-sync middleware, the backend pulls library data through Steam APIs and stores it in `SteamLibraries`. Ownership and playtime helpers then power “owned game” detection, playtime stats, and library-aware recommendations.

8. **Social and real-time layer**
   Real-time game chat is handled by Socket.IO in the backend’s `social/` modules, with separate text and voice handlers. Reviews and comments support `@mentions`, and utility functions create/delete related activities and notifications so social events propagate into user feeds and inboxes consistently.

9. **Recommendation service boundary**
   `gamiq` is an isolated ML backend. It exposes FastAPI endpoints for recommendation requests, but its main value is the two-stage retrieval pipeline: FAISS vector search for candidate generation, then ONNX cross-encoder reranking for final ranking. The backend calls this service internally, then enriches returned game IDs with application metadata before sending results to the frontend.

10. **Offline ML pipeline**
   The Python service also includes offline jobs for rebuilding embeddings, exporting models, converting artifacts, and training FAISS indexes. That indicates a clear separation between online inference and batch/model-maintenance workflows. Redis is used here for recommendation caching, while the backend uses Redis for rate limiting.

11. **Deployment and runtime topology**
   The repository contains both Docker Compose and Kubernetes manifests. In the containerized deployment, nginx serves the frontend and reverse proxies to the backend; the backend and `gamiq` run as separate services; Redis is shared; and certbot handles TLS renewal. The Kubernetes manifests add ingress, HPA, storage, and a monitoring stack (Prometheus, Grafana, Loki, Alertmanager, exporters).

12. **Engineering/tooling signals**
   The repo is structured for independent development of each tier: frontend linting/testing, backend Node runtime, and Python pytest coverage for the ML service. Shared review tags and utility mappings appear in both frontend and backend, which suggests deliberate contract alignment between UI and server-side review/game logic.

Main entry points: [`backend/server.js`](https://github.com/vishal-shaw20/game-social/blob/main/backend/server.js) (Express Server), [`gamiq/main.py`](https://github.com/vishal-shaw20/game-social/blob/main/gamiq/main.py) (Reco API), [`docker-compose.yml`](https://github.com/vishal-shaw20/game-social/blob/main/docker-compose.yml) (Deploy Stack), [`backend/routes/friendRoutes.js`](https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/friendRoutes.js) (Social Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["React SPA<br/>vite app<br/>[App.jsx]"]
  node_fe_views["User Views<br/>ui screens"]
  node_fe_hooks["Client Hooks<br/>state/hooks"]
  node_fe_shared["Shared Tags<br/>ui contract<br/>[reviewTags.js]"]
end

subgraph group_backend["Backend"]
  node_be_server["Express Server<br/>node service<br/>[server.js]"]
  node_be_auth["Auth Flows<br/>passport auth<br/>[authRoutes.js]"]
  node_be_profile["Profiles<br/>user routes<br/>[profile.js]"]
  node_be_social["Social Routes<br/>social api<br/>[friendRoutes.js]"]
  node_be_catalog["Catalog Search<br/>game api<br/>[searchRoutes.js]"]
  node_be_sync["Steam Sync<br/>sync layer<br/>[steamLibrary.js]"]
  node_be_realtime["Socket Server<br/>realtime hub<br/>[socketServer.js]"]
  node_be_jobs["Catalog Jobs<br/>cron pipeline<br/>[rawg_games.js]"]
  node_be_models[("App Models<br/>mongo models<br/>[User.js]")]
end

subgraph group_gamiq["gamiq"]
  node_gq_api["Reco API<br/>fastapi service<br/>[main.py]"]
  node_gq_retrieval["Retrieval<br/>faiss search<br/>[query_faiss.py]"]
  node_gq_ranker["Reranker<br/>onnx ranker<br/>[reranker.py]"]
  node_gq_offline["Offline ML<br/>batch pipeline"]
end

subgraph group_infra["Infrastructure"]
  node_data_mongo[("MongoDB<br/>document store")]
  node_data_pg[("PostgreSQL<br/>relational store")]
  node_data_redis[("Redis<br/>cache")]
  node_deploy["Deploy Stack<br/>containers/k8s<br/>[docker-compose.yml]"]
end

node_fe_app -->|"renders"| node_fe_views
node_fe_views -->|"uses"| node_fe_hooks
node_fe_views -->|"REST/Socket.IO"| node_be_server
node_fe_shared -.->|"tag contract"| node_be_social
node_be_server -->|"routes auth"| node_be_auth
node_be_server -->|"routes profiles"| node_be_profile
node_be_server -->|"routes social"| node_be_social
node_be_server -->|"routes catalog"| node_be_catalog
node_be_server -->|"syncs libraries"| node_be_sync
node_be_server -->|"hosts sockets"| node_be_realtime
node_be_server -->|"scheduled ingest"| node_be_jobs
node_be_social -->|"persists"| node_be_models
node_be_sync -->|"stores libraries"| node_be_models
node_be_catalog -->|"queries"| node_data_pg
node_be_social -->|"reads/writes"| node_data_mongo
node_be_sync -->|"updates"| node_data_mongo
node_be_server -->|"rate limits"| node_data_redis
node_be_server -->|"requests recs"| node_gq_api
node_gq_api -->|"candidates"| node_gq_retrieval
node_gq_api -->|"reranks"| node_gq_ranker
node_gq_offline -->|"builds index"| node_gq_retrieval
node_gq_offline -->|"exports model"| node_gq_ranker
node_gq_api -->|"caches"| node_data_redis
node_be_catalog -->|"ingests"| node_data_pg
node_deploy -->|"serves"| node_fe_app
node_deploy -->|"runs"| node_be_server
node_deploy -->|"runs"| node_gq_api
node_deploy -->|"shares"| node_data_redis

click node_fe_app "https://github.com/vishal-shaw20/game-social/blob/main/frontend/src/App.jsx"
click node_fe_views "https://github.com/vishal-shaw20/game-social/tree/main/frontend/src/components"
click node_fe_hooks "https://github.com/vishal-shaw20/game-social/tree/main/frontend/src/hooks"
click node_fe_shared "https://github.com/vishal-shaw20/game-social/blob/main/frontend/src/shared/reviewTags.js"
click node_be_server "https://github.com/vishal-shaw20/game-social/blob/main/backend/server.js"
click node_be_auth "https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/authRoutes.js"
click node_be_profile "https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/profile.js"
click node_be_social "https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/friendRoutes.js"
click node_be_catalog "https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/searchRoutes.js"
click node_be_sync "https://github.com/vishal-shaw20/game-social/blob/main/backend/services/steamLibrary.js"
click node_be_realtime "https://github.com/vishal-shaw20/game-social/blob/main/backend/social/socketServer.js"
click node_be_jobs "https://github.com/vishal-shaw20/game-social/blob/main/backend/cron/rawg_games.js"
click node_be_models "https://github.com/vishal-shaw20/game-social/blob/main/backend/models/User.js"
click node_gq_api "https://github.com/vishal-shaw20/game-social/blob/main/gamiq/main.py"
click node_gq_retrieval "https://github.com/vishal-shaw20/game-social/blob/main/gamiq/recommender/inference/query_faiss.py"
click node_gq_ranker "https://github.com/vishal-shaw20/game-social/blob/main/gamiq/recommender/inference/reranker.py"
click node_gq_offline "https://github.com/vishal-shaw20/game-social/blob/main/gamiq/recommender/offline/rebuild_embeddings.py"
click node_deploy "https://github.com/vishal-shaw20/game-social/blob/main/docker-compose.yml"

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_fe_app,node_fe_views,node_fe_hooks,node_fe_shared toneBlue
class node_be_server,node_be_auth,node_be_profile,node_be_social,node_be_catalog,node_be_sync,node_be_realtime,node_be_jobs,node_be_models toneAmber
class node_gq_api,node_gq_retrieval,node_gq_ranker,node_gq_offline toneMint
class node_data_mongo,node_data_pg,node_data_redis,node_deploy toneRose
```

## Components

### Frontend

React SPA for browsing, profiles, libraries, social views, and chat.

- [React SPA](https://github.com/vishal-shaw20/game-social/blob/main/frontend/src/App.jsx): vite app · Client-side presentation shell and application entrypoint. · `frontend/src/App.jsx`
- [User Views](https://github.com/vishal-shaw20/game-social/tree/main/frontend/src/components): ui screens · Primary screens for home, search, details, library, profile, and social interaction. · `frontend/src/components`
- [Client Hooks](https://github.com/vishal-shaw20/game-social/tree/main/frontend/src/hooks): state/hooks · Auth, socket, carousel, and chat hooks that coordinate client behavior. · `frontend/src/hooks`
- [Shared Tags](https://github.com/vishal-shaw20/game-social/blob/main/frontend/src/shared/reviewTags.js): ui contract · Review tag vocabulary shared with the backend. · `frontend/src/shared/reviewTags.js`

### Backend

Express application hub for auth, social, catalog, and sync flows.

- [Express Server](https://github.com/vishal-shaw20/game-social/blob/main/backend/server.js): node service · Main backend entrypoint and request orchestration layer. · `backend/server.js`
- [Auth Flows](https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/authRoutes.js): passport auth · Google, Steam, email/password, OTP, and account-linking flows. · `backend/routes/authRoutes.js`
- [Profiles](https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/profile.js): user routes · User profile and identity endpoints. · `backend/routes/profile.js`
- [Social Routes](https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/friendRoutes.js): social api · Friends, reviews, comments, and notifications endpoints. · `backend/routes/friendRoutes.js`
- [Catalog Search](https://github.com/vishal-shaw20/game-social/blob/main/backend/routes/searchRoutes.js): game api · Search, trending, and game lookup endpoints over the merged game catalog. · `backend/routes/searchRoutes.js`
- [Steam Sync](https://github.com/vishal-shaw20/game-social/blob/main/backend/services/steamLibrary.js): sync layer · Steam library synchronization and ownership/playtime helpers. · `backend/services/steamLibrary.js`
- [Socket Server](https://github.com/vishal-shaw20/game-social/blob/main/backend/social/socketServer.js): realtime hub · Socket.IO server for chat and live social updates. · `backend/social/socketServer.js`
- [Catalog Jobs](https://github.com/vishal-shaw20/game-social/blob/main/backend/cron/rawg_games.js): cron pipeline · Scheduled RAWG and SteamSpy ingestion tasks. · `backend/cron/rawg_games.js`
- [App Models](https://github.com/vishal-shaw20/game-social/blob/main/backend/models/User.js): mongo models · Users, reviews, comments, notifications, activities, and Steam libraries. · `backend/models/User.js`

### gamiq

FastAPI recommendation service with online inference and offline ML jobs.

- [Reco API](https://github.com/vishal-shaw20/game-social/blob/main/gamiq/main.py): fastapi service · Online recommendation endpoints for candidate retrieval and ranking. · `gamiq/main.py`
- [Retrieval](https://github.com/vishal-shaw20/game-social/blob/main/gamiq/recommender/inference/query_faiss.py): faiss search · FAISS-based candidate generation from embeddings. · `gamiq/recommender/inference/query_faiss.py`
- [Reranker](https://github.com/vishal-shaw20/game-social/blob/main/gamiq/recommender/inference/reranker.py): onnx ranker · Cross-encoder reranking of retrieved candidates. · `gamiq/recommender/inference/reranker.py`
- [Offline ML](https://github.com/vishal-shaw20/game-social/blob/main/gamiq/recommender/offline/rebuild_embeddings.py): batch pipeline · Embedding rebuild, export, and FAISS/ONNX artifact maintenance jobs. · `gamiq/recommender/offline/rebuild_embeddings.py`

### Infrastructure

Shared data stores, deployment, and observability.

- **MongoDB**: document store · Social, account, review, notification, and library data.
- **PostgreSQL**: relational store · Game catalog and retrieval-oriented data including embeddings.
- **Redis**: cache · Rate limiting and recommendation caching.
- [Deploy Stack](https://github.com/vishal-shaw20/game-social/blob/main/docker-compose.yml): containers/k8s · Docker Compose, nginx, Kubernetes, ingress, storage, and monitoring manifests. · `docker-compose.yml`

## Connections

- React SPA → User Views: renders · App composes the main UI areas.
- User Views → Client Hooks: uses · Screens depend on auth and socket hooks.
- User Views → Express Server: REST/Socket.IO · Client talks to backend APIs and realtime channels.
- Shared Tags → Social Routes: tag contract · Shared review tags keep UI and server aligned.
- Express Server → Auth Flows: routes auth · Server exposes identity and login flows.
- Express Server → Profiles: routes profiles · Server serves profile and account endpoints.
- Express Server → Social Routes: routes social · Server handles friends, reviews, comments, and notifications.
- Express Server → Catalog Search: routes catalog · Server exposes search, trending, and game lookup.
- Express Server → Steam Sync: syncs libraries · Server triggers Steam library ownership and playtime sync.
- Express Server → Socket Server: hosts sockets · Server owns Socket.IO chat and live event delivery.
- Express Server → Catalog Jobs: scheduled ingest · Server-side jobs refresh catalog data.
- Social Routes → App Models: persists · Social actions write to Mongo-backed collections.
- Steam Sync → App Models: stores libraries · Steam library snapshots are saved with app data.
- Catalog Search → PostgreSQL: queries · Search and lookup read the game catalog from PostgreSQL.
- Social Routes → MongoDB: reads/writes · Social and identity workflows use MongoDB.
- Steam Sync → MongoDB: updates · Steam ownership and playtime state is stored in MongoDB.
- Express Server → Redis: rate limits · Redis supports request limiting in the backend.
- Express Server → Reco API: requests recs · Backend calls the recommendation service and enriches results.
- Reco API → Retrieval: candidates · API uses FAISS retrieval for initial matches.
- Reco API → Reranker: reranks · API applies the cross-encoder to final ranking.
- Offline ML → Retrieval: builds index · Offline jobs train and rebuild FAISS artifacts.
- Offline ML → Reranker: exports model · Offline jobs export and maintain the reranker artifact.
- Reco API → Redis: caches · Recommendation responses are cached in Redis.
- Catalog Search → PostgreSQL: ingests · Scheduled RAWG and SteamSpy jobs refresh catalog data.
- Deploy Stack → React SPA: serves · Deployment stack serves the frontend through nginx/container runtime.
- Deploy Stack → Express Server: runs · Deployment stack runs the backend service.
- Deploy Stack → Reco API: runs · Deployment stack runs the recommendation service.
- Deploy Stack → Redis: shares · Shared Redis is deployed alongside services.
