cal/mantimon-tcg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7fcb86ff51
mantimon-tcg/backend/PROJECT_PLAN_MASTER.json
Cal Corum ebe776d54d Update project plans and documentation for Phase 3 completion 
Project plan updates:
- Mark all 14 Phase 3 tasks as completed
- Update acceptance criteria to met
- Update master plan status to Phase 4 next
- Add detailed deliverables list for Phase 3

Documentation updates:
- Add UNSET sentinel pattern to CLAUDE.md
- Document when to use UNSET vs None for nullable fields

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 15:26:01 -06:00

269 lines
9.1 KiB
JSON
Raw Blame History

{
"meta": {
"version": "1.0.0",
"created": "2026-01-27",
"lastUpdated": "2026-01-28",
"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": 4,
"status": "Phases 0-3 complete, Phase 4 (Game Service + WebSocket) 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": "NOT_STARTED",
"description": "Real-time gameplay, reconnection, turn timeouts",
"planFile": "project_plans/PHASE_4_GAME_SERVICE.json",
"estimatedWeeks": "2-3",
"dependencies": ["PHASE_3"],
"deliverables": [
"WebSocket connection manager",
"Message protocol specification",
"GameService (create, execute, persist, resume)",
"Turn-boundary persistence to Postgres",
"Reconnection handling",
"Turn timeout system",
"Replay data capture",
"Spectator mode (optional)"
]
},
{
"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"]
}
Reference in New Issue View Git Blame Copy Permalink