Elemental Circle Game Backend

Problem & Context

Backend for a strategic elemental card game designed for real-time multiplayer battles. Focus on building a robust API and game engine that can support web, mobile, and desktop clients through a single backend.

Architecture Overview

The game uses a hybrid architecture to combine real-time performance with reliable persistence:

• FastAPI backend exposing REST and WebSocket endpoints.
• Redis for ultra-fast, in-memory game state (hands, scores, turn info).
• PostgreSQL with SQLAlchemy for users, game events, and analytics.
• Containerised with Docker, ready for local or cloud deployment.

Key Backend Components

• HybridGameService: Orchestrates Redis + PostgreSQL operations.
• RedisGameService: Manages real-time game state with TTL and pub/sub.
• EventService: Logs detailed game events for analytics and debugging.
• Dynamic Card Engine: Generates cards in code without database dependency.

Gameplay & Rules

Element-based combat system similar to rock–paper–scissors, implemented in the backend:

• Elements: Fire, Water, Grass with symmetric advantages and multipliers.
• Cards have values (1–8) and element; backend applies elemental multipliers.
• Turn-based system: one player plays onboard card, the other counter-plays.
• Scoring formula drives points and winner calculation per round and game.

API & Real-time Layer

• JWT-secured REST endpoints for auth, game creation, joining, and state inspection.
• WebSocket endpoint for live game updates and moves.
• Health and utility scripts for local development and simulations (AI vs player, AI vs AI).

Future Roadmap

• Smarter AI opponents and tournament modes.
• Flutter frontends (web, mobile, desktop) connected to the same backend.
• Cloud deployment with load balancing and analytics for balancing and anti-cheat.