{ "meta": { "version": "1.0.0", "created": "2026-01-27", "lastUpdated": "2026-01-30", "planType": "master", "projectName": "Mantimon TCG - Backend Services", "description": "Live service backend for play.mantimon.com - server-authoritative multiplayer TCG with campaign mode, free-play, and F2P monetization", "totalPhases": 6, "completedPhases": 5, "status": "Phases 0-4 complete, Phase 5 (Campaign Mode) up next" }, "architectureDecisions": { "deployment": "Online-first live service at play.mantimon.com", "database": "PostgreSQL 15+ for durable storage", "cache": "Redis 7+ for game state, matchmaking, sessions", "gameState": "Redis primary (fast), Postgres write-behind at turn boundaries", "api": "FastAPI REST + python-socketio WebSocket", "auth": "OAuth 2.0 (Google, Discord) with JWT sessions", "cardData": "Bundled JSON in repo, loaded at runtime", "offlineSupport": "Core engine forkable, full offline mode deferred", "replayData": "Capture from start for future replay feature" }, "businessRules": { "monetization": { "model": "F2P with optional purchases", "fullCollectionF2P": true, "premiumFeatures": ["cosmetics", "convenience", "battle_pass"], "premiumDuration": "time-limited (subscription style)", "noPay2Win": true }, "currency": { "name": "Mantibucks", "symbol": "₼" }, "deckLimits": { "free": 5, "premium": "unlimited" }, "starterDecks": { "count": 5, "types": ["grass", "fire", "water", "psychic", "lightning"], "rotation": "Two deck types rotate with current set releases", "classic": ["grass", "fire", "water"], "rotating": ["psychic", "lightning"] }, "boosterPacks": { "structure": "X slots per pack, each slot has individual rarity probabilities", "acquisition": ["campaign_wins", "daily_rewards", "purchases"] }, "energyDeck": { "default": true, "configurable": true, "note": "Mantimon house rules default, standard Pokemon TCG supported" }, "deckValidation": { "campaign": "Requires card ownership", "freeplay": "Full collection unlocked" } }, "phases": [ { "id": "PHASE_0", "name": "Core Game Engine", "status": "COMPLETE", "description": "Pure game logic - GameEngine, models, effects, validation, turn management", "planFile": "PROJECT_PLAN.json", "deliverables": [ "GameEngine orchestrator", "RulesConfig system", "All action types and validation", "Effect handler system with 12 built-in handlers", "Turn manager with status conditions", "Win condition checker", "Visibility filter (hidden info security)", "Card scraper with 372 cards + images", "Engine validation script (29 test scenarios)", "833 initial tests (now 1072 total with all phases)" ], "completedDate": "2026-01-27" }, { "id": "PHASE_1", "name": "Database + Infrastructure", "status": "COMPLETE", "description": "PostgreSQL models, Redis caching, CardService, environment config", "planFile": "project_plans/PHASE_1_DATABASE.json", "dependencies": ["PHASE_0"], "deliverables": [ "SQLAlchemy async models (User, GameHistory, OAuthLinkedAccount)", "Alembic migrations", "Redis connection utilities", "GameStateManager (Redis + Postgres write-behind)", "CardService (JSON → CardDefinition)", "Environment config (dev/staging/prod)", "Docker compose for local dev" ], "completedDate": "2026-01-27" }, { "id": "PHASE_2", "name": "Authentication", "status": "COMPLETE", "description": "OAuth login, JWT sessions, user management", "planFile": "project_plans/PHASE_2_AUTH.json", "dependencies": ["PHASE_1"], "deliverables": [ "OAuth integration (Google, Discord)", "JWT token management with refresh tokens", "User creation/login endpoints", "FastAPI auth dependencies (CurrentUser, DbSession)", "Account linking (multiple providers per user)", "Premium tier with expiration tracking", "98 new tests, 1072 total tests" ], "completedDate": "2026-01-28" }, { "id": "PHASE_3", "name": "Collections + Decks", "status": "COMPLETE", "description": "Card ownership, deck building, starter deck selection", "planFile": "project_plans/PHASE_3_COLLECTION_DECKS.json", "estimatedWeeks": "1-2", "dependencies": ["PHASE_2"], "deliverables": [ "CollectionService with repository pattern", "DeckService with DI and DeckConfig from request", "DeckValidator pure function with comprehensive rules", "Collections API (/collections/me, /collections/me/cards/{id}, admin endpoint)", "Decks API (/decks CRUD, /decks/validate)", "Starter deck endpoints (/users/me/starter-deck, /users/me/starter-status)", "5 starter deck definitions (grass, fire, water, psychic, lightning)", "UNSET sentinel pattern for nullable field updates", "Race condition protection via unique partial index", "Admin API key authentication", "Energy type validation", "127 new tests, 1199 total tests" ], "completedDate": "2026-01-28" }, { "id": "PHASE_4", "name": "Game Service + WebSocket", "status": "COMPLETE", "description": "Real-time gameplay, reconnection, turn timeouts", "planFile": "project_plans/PHASE_4_GAME_SERVICE.json", "dependencies": ["PHASE_3"], "deliverables": [ "WebSocket server with python-socketio (ASGI integration)", "ConnectionManager with Redis-backed session tracking", "Socket.IO JWT authentication middleware", "GameService (create, join, execute, resign, end)", "WebSocket message schemas (Pydantic discriminated unions)", "/game namespace event handlers with room broadcasting", "TurnTimeoutService with percentage-based warnings", "Reconnection flow with auto-rejoin and grace period", "REST endpoints for game management (POST /games, GET /games/{id})", "Spectator mode with filtered state", "Turn-boundary persistence to Postgres", "306 new tests, 1505 total tests" ], "completedDate": "2026-01-30" }, { "id": "PHASE_5", "name": "Campaign Mode", "status": "NOT_STARTED", "description": "Single-player experience with NPCs, progression, rewards", "planFile": "project_plans/PHASE_5_CAMPAIGN.json", "estimatedWeeks": "3-4", "dependencies": ["PHASE_4"], "deliverables": [ "Club and NPC data structures", "CampaignService (progression, save/load)", "AI system (RuleBasedAI, DifficultyScaledAI)", "NPC deck definitions", "Reward system (medals, booster packs, Mantibucks)", "Booster pack opening with slot-based rarities", "Campaign REST endpoints" ] }, { "id": "PHASE_6", "name": "Free-Play Multiplayer", "status": "NOT_STARTED", "description": "PvP matchmaking, custom rules, ranked mode", "planFile": "project_plans/PHASE_6_MULTIPLAYER.json", "estimatedWeeks": "2-3", "dependencies": ["PHASE_4"], "deliverables": [ "Matchmaking queue (Redis-backed)", "Invite link system (private games)", "RulesConfig customization API", "Match history", "Ranked mode with Elo/MMR (optional)", "Leaderboards (optional)" ] } ], "futurePhases": [ { "id": "FUTURE_P2P", "name": "P2P Multiplayer", "description": "Peer-to-peer for offline/LAN play (host-authoritative)", "priority": "nice-to-have" }, { "id": "FUTURE_REPLAYS", "name": "Replay System", "description": "Playback recorded games (data captured from Phase 4)", "priority": "nice-to-have" }, { "id": "FUTURE_ML_AI", "name": "ML-Based AI", "description": "Neural network opponents", "priority": "nice-to-have" }, { "id": "FUTURE_OFFLINE", "name": "Offline Fork", "description": "Standalone offline package with SQLite", "priority": "nice-to-have" }, { "id": "FUTURE_TRADING", "name": "Trading System", "description": "Player-to-player card trading", "priority": "nice-to-have" }, { "id": "FUTURE_TOURNAMENTS", "name": "Tournament Mode", "description": "Organized competitive events", "priority": "nice-to-have" } ], "infrastructure": { "required": { "postgresql": "15+", "redis": "7+", "python": "3.11+" }, "development": { "docker": "Docker compose for local Postgres + Redis", "testing": "pytest-asyncio, testcontainers" }, "production": { "deployment": "Kubernetes (future)", "cdn": "Card images served via CDN", "monitoring": "TBD" } }, "securityConsiderations": [ "All game logic server-authoritative", "Hidden information never sent to clients (from Phase 0)", "OAuth tokens never stored, only OAuth IDs", "JWT tokens short-lived with refresh mechanism", "Rate limiting on all endpoints", "Action validation on every request (from Phase 0)" ], "totalEstimatedWeeks": "12-17", "criticalPath": ["PHASE_1", "PHASE_2", "PHASE_3", "PHASE_4", "PHASE_5"] }