How vishal-shaw20/game-social works
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: server.js Express Server · main.py Reco API · docker-compose.yml Deploy Stack · friendRoutes.js Social Routes
Components 21
Frontend
React SPA for browsing, profiles, libraries, social views, and chat.
- React SPA · Client-side presentation shell and application entrypoint.
frontend/src/App.jsx - User Views · Primary screens for home, search, details, library, profile, and social interaction.
frontend/src/components - Client Hooks · Auth, socket, carousel, and chat hooks that coordinate client behavior.
frontend/src/hooks - Shared Tags · 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 · Main backend entrypoint and request orchestration layer.
backend/server.js - Auth Flows · Google, Steam, email/password, OTP, and account-linking flows.
backend/routes/authRoutes.js - Profiles · User profile and identity endpoints.
backend/routes/profile.js - Social Routes · Friends, reviews, comments, and notifications endpoints.
backend/routes/friendRoutes.js - Catalog Search · Search, trending, and game lookup endpoints over the merged game catalog.
backend/routes/searchRoutes.js - Steam Sync · Steam library synchronization and ownership/playtime helpers.
backend/services/steamLibrary.js - Socket Server · Socket.IO server for chat and live social updates.
backend/social/socketServer.js - Catalog Jobs · Scheduled RAWG and SteamSpy ingestion tasks.
backend/cron/rawg_games.js - App 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 · Online recommendation endpoints for candidate retrieval and ranking.
gamiq/main.py - Retrieval · FAISS-based candidate generation from embeddings.
gamiq/recommender/inference/query_faiss.py - Reranker · Cross-encoder reranking of retrieved candidates.
gamiq/recommender/inference/reranker.py - Offline ML · Embedding rebuild, export, and FAISS/ONNX artifact maintenance jobs.
gamiq/recommender/offline/rebuild_embeddings.py
Infrastructure
Shared data stores, deployment, and observability.
- MongoDB · Social, account, review, notification, and library data.
- PostgreSQL · Game catalog and retrieval-oriented data including embeddings.
- Redis · Rate limiting and recommendation caching.
- Deploy Stack · Docker Compose, nginx, Kubernetes, ingress, storage, and monitoring manifests.
docker-compose.yml
Connections 28
- 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.